> ## Documentation Index > Fetch the complete documentation index at: https://bun.ll1025.cn/llms.txt > Use this file to discover all available pages before exploring further. # 工具 > 使用 Bun 的实用函数来操作运行时 ## `Bun.version` 一个 `string`，包含当前运行的 `bun` CLI 的版本号。 ```ts terminal icon="terminal" theme={null} Bun.version; // => "1.3.3" ``` ## `Bun.revision` 编译出当前 `bun` CLI 的 [Bun](https://github.com/oven-sh/bun) git 提交哈希。 ```ts terminal icon="terminal" theme={null} Bun.revision; // => "f02561530fda1ee9396f51c8bc99b38716e38296" ``` ## `Bun.env` `process.env` 的别名。 ## `Bun.main` 当前程序入口点的绝对路径（使用 `bun run` 执行的文件）。 ```ts script.ts theme={null} Bun.main; // /path/to/script.ts ``` 使用此方法判断脚本是直接执行还是被其他脚本导入。 ```ts theme={null} if (import.meta.path === Bun.main) { // 此脚本正在被直接执行 } else { // 此文件正从另一个脚本导入 } ``` 这类似于 Node.js 中的 [`require.main = module` 技巧](https://stackoverflow.com/questions/6398196/detect-if-called-through-require-or-directly-by-command-line)。 ## `Bun.sleep()` `Bun.sleep(ms: number)` 返回一个在指定毫秒数后解决的 `Promise`。 ```ts theme={null} console.log("hello"); await Bun.sleep(1000); console.log("hello one second later!"); ``` 或者，传递一个 `Date` 对象来接收一个在该时间点解决的 `Promise`。 ```ts theme={null} const oneSecondInFuture = new Date(Date.now() + 1000); console.log("hello"); await Bun.sleep(oneSecondInFuture); console.log("hello one second later!"); ``` ## `Bun.sleepSync()` `Bun.sleepSync(ms: number)` `Bun.sleep` 的阻塞同步版本。 ```ts theme={null} console.log("hello"); Bun.sleepSync(1000); // 阻塞线程一秒 console.log("hello one second later!"); ``` ## `Bun.which()` `Bun.which(bin: string)` 返回可执行文件的路径，类似于在终端中键入 `which`。 ```ts theme={null} const ls = Bun.which("ls"); console.log(ls); // "/usr/bin/ls" ``` 默认情况下，Bun 查看当前的 `PATH` 环境变量来确定路径。要配置 `PATH`： ```ts theme={null} const ls = Bun.which("ls", { PATH: "/usr/local/bin:/usr/bin:/bin", }); console.log(ls); // "/usr/bin/ls" ``` 传递 `cwd` 选项以从特定目录内解析可执行文件。 ```ts theme={null} const ls = Bun.which("ls", { cwd: "/tmp", PATH: "", }); console.log(ls); // null ``` 这是 [`which`](https://www.npmjs.com/package/which) npm 包的内置替代方案。 ## `Bun.randomUUIDv7()` `Bun.randomUUIDv7()` 返回一个 [UUID v7](https://www.ietf.org/archive/id/draft-peabody-dispatch-new-uuid-format-01.html#name-uuidv7-layout-and-bit-order)，它是单调递增的，适合排序和数据库使用。 ```ts theme={null} import { randomUUIDv7 } from "bun"; const id = randomUUIDv7(); // => "0192ce11-26d5-7dc3-9305-1426de888c5a" ``` UUID v7 是一个 128 位值，编码了当前时间戳、一个随机值和一个计数器。时间戳使用最低 48 位编码，随机值和计数器使用剩余位编码。 `timestamp` 参数默认为当前时间（毫秒）。当时钟向前移动时，计数器会重置为一个新的伪随机整数（12 位计数器的高位保持清零，因此在翻转前至少还有 2048 个值）。如果时钟尚未超过上次发出的时间戳，Bun 会重用上次发出的时间戳并递增计数器。如果计数器翻转，Bun 会向前推进发出的时间戳而不是回绕计数器，因此返回的 UUID 保持严格递增（RFC 9562 §6.2）。计数器是原子操作且线程安全的，因此在同一进程中同一时间戳下，来自多个 Worker 的 `Bun.randomUUIDv7()` 调用不会产生冲突的计数器值。 当你传递显式的 `timestamp` 时，Bun 会按原样编码该值，并为其维护独立的计数器，因此使用显式时间戳的调用不会观察或更改默认路径使用的单调状态。使用相同显式时间戳的重复调用会递增该独立计数器（并在翻转时向前推进发出的时间戳），以便它们保持可排序；使用不同显式时间戳的调用会重置它。 UUID 的最后 8 个字节是加密安全的随机值。它使用与 `crypto.randomUUID()` 相同的随机数生成器（来自 BoringSSL，而 BoringSSL 又来自通常由底层硬件提供的平台特定系统随机数生成器）。 ```ts theme={null} namespace Bun { function randomUUIDv7(encoding?: "hex" | "base64" | "base64url" = "hex", timestamp?: number = Date.now()): string; /** * 如果传递 "buffer"，则返回 16 字节的 buffer 而不是字符串。 */ function randomUUIDv7(encoding: "buffer", timestamp?: number = Date.now()): Buffer; // 如果只传递时间戳，则返回十六进制字符串 function randomUUIDv7(timestamp?: number = Date.now()): string; } ``` 传递 `"buffer"` 作为编码以获取 16 字节的 buffer 而不是字符串。这可以避免字符串转换开销。 ```ts buffer.ts theme={null} const buffer = Bun.randomUUIDv7("buffer"); ``` `base64` 和 `base64url` 编码也受支持，当你想要稍微短一点的字符串时可使用。 ```ts base64.ts theme={null} const base64 = Bun.randomUUIDv7("base64"); const base64url = Bun.randomUUIDv7("base64url"); ``` ## `Bun.peek()` `Bun.peek(prom: Promise)` 读取 Promise 的结果而无需 `await` 或 `.then`，但仅限于该 Promise 已经完成或拒绝的情况。 ````ts theme={null} import { peek } from "bun"; const promise = Promise.resolve("hi"); // 无需 await！ const result = peek(promise); console.log(result); // "hi" " 使用它来避免在性能敏感的代码中产生额外的微任务。这是一个高级 API；在生产环境中使用前请先查看以下示例。 ```ts import { peek } from "bun"; import { expect, test } from "bun:test"; test("peek", () => { const promise = Promise.resolve(true); // 无需 await！ expect(peek(promise)).toBe(true); // 如果再次 peek，它返回相同的值 const again = peek(promise); expect(again).toBe(true); // 如果 peek 一个非 Promise 的值，它返回该值本身 const value = peek(42); expect(value).toBe(42); // 如果 peek 一个待定的 Promise，它返回该 Promise 本身 const pending = new Promise(() => {}); expect(peek(pending)).toBe(pending); // 如果 peek 一个已拒绝的 Promise，它会： // - 返回错误 // - 不将该 Promise 标记为已处理 const rejected = Promise.reject(new Error("Successfully tested promise rejection")); expect(peek(rejected).message).toBe("Successfully tested promise rejection"); }); ```` `peek.status` 读取 Promise 的状态而不解决它。 ```ts theme={null} import { peek } from "bun"; import { expect, test } from "bun:test"; test("peek.status", () => { const promise = Promise.resolve(true); expect(peek.status(promise)).toBe("fulfilled"); const pending = new Promise(() => {}); expect(peek.status(pending)).toBe("pending"); const rejected = Promise.reject(new Error("oh nooo")); expect(peek.status(rejected)).toBe("rejected"); }); ``` ## `Bun.openInEditor()` 在默认编辑器中打开文件。Bun 从 `$VISUAL` 或 `$EDITOR` 环境变量自动检测你的编辑器。 ```ts theme={null} const currentFile = import.meta.url; Bun.openInEditor(currentFile); ``` 你可以通过 [`bunfig.toml`](/runtime/bunfig) 中的 `debug.editor` 设置来覆盖此项。 ```toml bunfig.toml icon="settings" theme={null} [debug] # [!code ++] editor = "code" # [!code ++] ``` 或者使用 `editor` 参数指定编辑器。你也可以指定行号和列号。 ```ts theme={null} Bun.openInEditor(import.meta.url, { editor: "vscode", // 或 "subl" line: 10, column: 5, }); ``` ## `Bun.deepEquals()` 递归检查两个对象是否相等。`bun:test` 中的 `expect().toEqual()` 内部使用此方法。 ```ts theme={null} const foo = { a: 1, b: 2, c: { d: 3 } }; // true Bun.deepEquals(foo, { a: 1, b: 2, c: { d: 3 } }); // false Bun.deepEquals(foo, { a: 1, b: 2, c: { d: 4 } }); ``` 传递第三个布尔参数以启用"严格"模式。测试运行器中的 `expect().toStrictEqual()` 使用此模式。 ```ts theme={null} const a = { entries: [1, 2] }; const b = { entries: [1, 2], extra: undefined }; Bun.deepEquals(a, b); // => true Bun.deepEquals(a, b, true); // => false ``` 在严格模式下，以下情况被视为不相等： ```ts theme={null} // undefined 值 Bun.deepEquals({}, { a: undefined }, true); // false // undefined 在数组中 Bun.deepEquals(["asdf"], ["asdf", undefined], true); // false // 稀疏数组 Bun.deepEquals([, 1], [undefined, 1], true); // false // 对象字面量 vs 具有相同属性的实例 class Foo { a = 1; } Bun.deepEquals(new Foo(), { a: 1 }, true); // false ``` ## `Bun.escapeHTML()` `Bun.escapeHTML(value: string | object | number | boolean): string` 转义输入字符串中的以下字符： * `"` 变为 `"` * `&` 变为 `&` * `'` 变为 `'` * `<` 变为 `<` * `>` 变为 `>` 此函数针对大输入进行了优化。在 M1X 上，处理速度为 480 MB/s - 20 GB/s，具体取决于要转义的数据量以及是否包含非 ASCII 文本。非字符串类型在转义前会转换为字符串。 ## `Bun.stringWidth()` 比 `string-width` 快约 6,756 倍的替代方案 获取字符串在终端中显示时的列宽。支持 ANSI 转义码、emoji 和宽字符。 用法示例： ```ts theme={null} Bun.stringWidth("hello"); // => 5 Bun.stringWidth("\u001b[31mhello\u001b[0m"); // => 5 Bun.stringWidth("\u001b[31mhello\u001b[0m", { countAnsiEscapeCodes: true }); // => 12 ``` 使用它来对齐终端中的文本，或检查字符串是否包含 ANSI 转义码。 该 API 与 "string-width" npm 包一致，因此现有代码可以移植到 Bun，反之亦然。 [在此基准测试中](https://github.com/oven-sh/bun/blob/5147c0ba7379d85d4d1ed0714b84d6544af917eb/bench/snippets/string-width.mjs#L13)，对于长度超过约 500 个字符的输入，`Bun.stringWidth` 比 `string-width` npm 包快约 6,756 倍。非常感谢 [sindresorhus](https://github.com/sindresorhus) 在 `string-width` 上的工作。 ```ts theme={null} ❯ bun string-width.mjs cpu: 13th Gen Intel(R) Core(TM) i9-13900 runtime: bun 1.0.29 (x64-linux) benchmark time (avg) (min … max) p75 p99 p995 ------------------------------------------------------------------------------------- ----------------------------- Bun.stringWidth 500 chars ascii 37.09 ns/iter (36.77 ns … 41.11 ns) 37.07 ns 38.84 ns 38.99 ns ❯ node string-width.mjs benchmark time (avg) (min … max) p75 p99 p995 ------------------------------------------------------------------------------------- ----------------------------- npm/string-width 500 chars ascii 249,710 ns/iter (239,970 ns … 293,180 ns) 250,930 ns 276,700 ns 281,450 ns ``` `Bun.stringWidth` 以原生代码实现，使用 SIMD 指令，并考虑了 Latin1、UTF-16 和 UTF-8 编码。它通过了 `string-width` 的测试。 1 纳秒（ns）是 10 亿分之一秒。单位换算： | 单位 | 1 毫秒 | | -- | --------- | | ns | 1,000,000 | | µs | 1,000 | | ms | 1 | ```bash terminal icon="terminal" theme={null} ❯ bun string-width.mjs cpu: 13th Gen Intel(R) Core(TM) i9-13900 runtime: bun 1.0.29 (x64-linux) benchmark time (avg) (min … max) p75 p99 p995 ------------------------------------------------------------------------------------- ----------------------------- Bun.stringWidth 5 chars ascii 16.45 ns/iter (16.27 ns … 19.71 ns) 16.48 ns 16.93 ns 17.21 ns Bun.stringWidth 50 chars ascii 19.42 ns/iter (18.61 ns … 27.85 ns) 19.35 ns 21.7 ns 22.31 ns Bun.stringWidth 500 chars ascii 37.09 ns/iter (36.77 ns … 41.11 ns) 37.07 ns 38.84 ns 38.99 ns Bun.stringWidth 5,000 chars ascii 216.9 ns/iter (215.8 ns … 228.54 ns) 216.23 ns 228.52 ns 228.53 ns Bun.stringWidth 25,000 chars ascii 1.01 µs/iter (1.01 µs … 1.01 µs) 1.01 µs 1.01 µs 1.01 µs Bun.stringWidth 7 chars ascii+emoji 54.2 ns/iter (53.36 ns … 58.19 ns) 54.23 ns 57.55 ns 57.94 ns Bun.stringWidth 70 chars ascii+emoji 354.26 ns/iter (350.51 ns … 363.96 ns) 355.93 ns 363.11 ns 363.96 ns Bun.stringWidth 700 chars ascii+emoji 3.3 µs/iter (3.27 µs … 3.4 µs) 3.3 µs 3.4 µs 3.4 µs Bun.stringWidth 7,000 chars ascii+emoji 32.69 µs/iter (32.22 µs … 45.27 µs) 32.7 µs 34.57 µs 34.68 µs Bun.stringWidth 35,000 chars ascii+emoji 163.35 µs/iter (161.17 µs … 170.79 µs) 163.82 µs 169.66 µs 169.93 µs Bun.stringWidth 8 chars ansi+emoji 66.15 ns/iter (65.17 ns … 69.97 ns) 66.12 ns 69.8 ns 69.87 ns Bun.stringWidth 80 chars ansi+emoji 492.95 ns/iter (488.05 ns … 499.5 ns) 494.8 ns 498.58 ns 499.5 ns Bun.stringWidth 800 chars ansi+emoji 4.73 µs/iter (4.71 µs … 4.88 µs) 4.72 µs 4.88 µs 4.88 µs Bun.stringWidth 8,000 chars ansi+emoji 47.02 µs/iter (46.37 µs … 67.44 µs) 46.96 µs 49.57 µs 49.63 µs Bun.stringWidth 40,000 chars ansi+emoji 234.45 µs/iter (231.78 µs … 240.98 µs) 234.92 µs 236.34 µs 236.62 µs Bun.stringWidth 19 chars ansi+emoji+ascii 135.46 ns/iter (133.67 ns … 143.26 ns) 135.32 ns 142.55 ns 142.77 ns Bun.stringWidth 190 chars ansi+emoji+ascii 1.17 µs/iter (1.16 µs … 1.17 µs) 1.17 µs 1.17 µs 1.17 µs Bun.stringWidth 1,900 chars ansi+emoji+ascii 11.45 µs/iter (11.26 µs … 20.41 µs) 11.45 µs 12.08 µs 12.11 µs Bun.stringWidth 19,000 chars ansi+emoji+ascii 114.06 µs/iter (112.86 µs … 120.06 µs) 114.25 µs 115.86 µs 116.15 µs Bun.stringWidth 95,000 chars ansi+emoji+ascii 572.69 µs/iter (565.52 µs … 607.22 µs) 572.45 µs 604.86 µs 605.21 µs ``` ```bash terminal icon="terminal" theme={null} ❯ node string-width.mjs cpu: 13th Gen Intel(R) Core(TM) i9-13900 runtime: node v21.4.0 (x64-linux) benchmark time (avg) (min … max) p75 p99 p995 -------------------------------------------------------------------------------------- ----------------------------- npm/string-width 5 chars ascii 3.19 µs/iter (3.13 µs … 3.48 µs) 3.25 µs 3.48 µs 3.48 µs npm/string-width 50 chars ascii 20.09 µs/iter (18.93 µs … 435.06 µs) 19.49 µs 21.89 µs 22.59 µs npm/string-width 500 chars ascii 249.71 µs/iter (239.97 µs … 293.18 µs) 250.93 µs 276.7 µs 281.45 µs npm/string-width 5,000 chars ascii 6.69 ms/iter (6.58 ms … 6.76 ms) 6.72 ms 6.76 ms 6.76 ms npm/string-width 25,000 chars ascii 139.57 ms/iter (137.17 ms … 143.28 ms) 140.49 ms 143.28 ms 143.28 ms npm/string-width 7 chars ascii+emoji 3.7 µs/iter (3.62 µs … 3.94 µs) 3.73 µs 3.94 µs 3.94 µs npm/string-width 70 chars ascii+emoji 23.93 µs/iter (22.44 µs … 331.2 µs) 23.15 µs 25.98 µs 30.2 µs npm/string-width 700 chars ascii+emoji 251.65 µs/iter (237.78 µs … 444.69 µs) 252.92 µs 325.89 µs 354.08 µs npm/string-width 7,000 chars ascii+emoji 4.95 ms/iter (4.82 ms … 5.19 ms) 5 ms 5.04 ms 5.19 ms npm/string-width 35,000 chars ascii+emoji 96.93 ms/iter (94.39 ms … 102.58 ms) 97.68 ms 102.58 ms 102.58 ms npm/string-width 8 chars ansi+emoji 3.92 µs/iter (3.45 µs … 4.57 µs) 4.09 µs 4.57 µs 4.57 µs npm/string-width 80 chars ansi+emoji 24.46 µs/iter (22.87 µs … 4.2 ms) 23.54 µs 25.89 µs 27.41 µs npm/string-width 800 chars ansi+emoji 259.62 µs/iter (246.76 µs … 480.12 µs) 258.65 µs 349.84 µs 372.55 µs npm/string-width 8,000 chars ansi+emoji 5.46 ms/iter (5.41 ms … 5.57 ms) 5.48 ms 5.55 ms 5.57 ms npm/string-width 40,000 chars ansi+emoji 108.91 ms/iter (107.55 ms … 109.5 ms) 109.25 ms 109.5 ms 109.5 ms npm/string-width 19 chars ansi+emoji+ascii 6.53 µs/iter (6.35 µs … 6.75 µs) 6.54 µs 6.75 µs 6.75 µs npm/string-width 190 chars ansi+emoji+ascii 55.52 µs/iter (52.59 µs … 352.73 µs) 54.19 µs 80.77 µs 167.21 µs npm/string-width 1,900 chars ansi+emoji+ascii 701.71 µs/iter (653.94 µs … 893.78 µs) 715.3 µs 855.37 µs 872.9 µs npm/string-width 19,000 chars ansi+emoji+ascii 27.19 ms/iter (26.89 ms … 27.41 ms) 27.28 ms 27.41 ms 27.41 ms npm/string-width 95,000 chars ansi+emoji+ascii 3.68 s/iter (3.66 s … 3.7 s) 3.69 s 3.7 s 3.7 s ``` TypeScript 定义： ```ts expandable theme={null} namespace Bun { export function stringWidth( /** * 要测量的字符串 */ input: string, options?: { /** * 如果为 `true`，将 ANSI 转义码计入字符串宽度。如果为 `false`，计算字符串宽度时忽略 ANSI 转义码。 * * @default false */ countAnsiEscapeCodes?: boolean; /** * 当宽度不明确且为 `true` 时，将 emoji 计为 1 个字符宽。如果为 `false`，emoji 计为 2 个字符宽。 * * @default true */ ambiguousIsNarrow?: boolean; }, ): number; } ``` *** ## `Bun.fileURLToPath()` 将 `file://` URL 转换为绝对路径。 ```ts theme={null} const path = Bun.fileURLToPath(new URL("file:///foo/bar.txt")); console.log(path); // "/foo/bar.txt" ``` *** ## `Bun.pathToFileURL()` 将绝对路径转换为 `file://` URL。 ```ts theme={null} const url = Bun.pathToFileURL("/foo/bar.txt"); console.log(url); // "file:///foo/bar.txt" ``` *** ## `Bun.gzipSync()` 使用 zlib 的 GZIP 算法压缩 `Uint8Array`。 ```ts theme={null} const buf = Buffer.from("hello".repeat(100)); // Buffer 继承自 Uint8Array const compressed = Bun.gzipSync(buf); buf; // => Uint8Array(500) compressed; // => Uint8Array(30) ``` 可选地，传递参数对象作为第二个参数： ```ts expandable theme={null} export type ZlibCompressionOptions = { /** * 使用的压缩级别。必须在 `-1` 到 `9` 之间。 * - 值为 `-1` 使用默认压缩级别（当前为 `6`） * - 值为 `0` 表示不压缩 * - 值为 `1` 表示压缩最少，速度最快 * - 值为 `9` 表示压缩最佳，速度最慢 */ level?: -1 | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9; /** * 为内部压缩状态分配多少内存。 * * 值为 `1` 使用最小内存，但速度慢且降低压缩比。 * * 值为 `9` 使用最大内存以获得最佳速度。默认值为 `8`。 */ memLevel?: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9; /** * 窗口大小的以 2 为底的对数（历史缓冲区的大小）。 * * 此参数的值越大，压缩效果越好，但内存使用也越多。 * * 支持以下取值范围： * - `9..15`：输出将包含 zlib 头和尾（Deflate） * - `-9..-15`：输出将**不**包含 zlib 头或尾（原始 Deflate） * - `25..31`（16+`9..15`）：输出将包含 gzip 头和尾（gzip） * * gzip 头将没有文件名、没有额外数据、没有注释、没有修改时间（设置为零）且没有头部 CRC。 */ windowBits?: | -9 | -10 | -11 | -12 | -13 | -14 | -15 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 25 | 26 | 27 | 28 | 29 | 30 | 31; /** * 调整压缩算法。 * * - `Z_DEFAULT_STRATEGY`：用于普通数据（默认） * - `Z_FILTERED`：用于由过滤器或预测器产生的数据 * - `Z_HUFFMAN_ONLY`：仅强制 Huffman 编码（无字符串匹配） * - `Z_RLE`：将匹配距离限制为一（运行长度编码） * - `Z_FIXED` 防止使用动态 Huffman 码 * * `Z_RLE` 设计为几乎与 `Z_HUFFMAN_ONLY` 一样快，但为 PNG 图像数据提供更好的压缩效果。 * * `Z_FILTERED` 强制更多 Huffman 编码和更少的字符串匹配，介于 * `Z_DEFAULT_STRATEGY` 和 `Z_HUFFMAN_ONLY` 之间。 * 过滤后的数据主要由分布有些随机的小值组成。 */ strategy?: number; }; ``` *** ## `Bun.gunzipSync()` 使用 zlib 的 GUNZIP 算法解压缩 `Uint8Array`。 ```ts theme={null} const buf = Buffer.from("hello".repeat(100)); // Buffer 继承自 Uint8Array const compressed = Bun.gzipSync(buf); const dec = new TextDecoder(); const uncompressed = Bun.gunzipSync(compressed); dec.decode(uncompressed); // => "hellohellohello..." ``` *** ## `Bun.deflateSync()` 使用 zlib 的 DEFLATE 算法压缩 `Uint8Array`。 ```ts theme={null} const buf = Buffer.from("hello".repeat(100)); const compressed = Bun.deflateSync(buf); buf; // => Buffer(500) compressed; // => Uint8Array(12) ``` 第二个参数支持与 [`Bun.gzipSync`](#bun-gzipsync) 相同的配置选项集合。 *** ## `Bun.inflateSync()` 使用 zlib 的 INFLATE 算法解压缩 `Uint8Array`。 ```ts theme={null} const buf = Buffer.from("hello".repeat(100)); const compressed = Bun.deflateSync(buf); const dec = new TextDecoder(); const decompressed = Bun.inflateSync(compressed); dec.decode(decompressed); // => "hellohellohello..." ``` *** ## `Bun.zstdCompress()` / `Bun.zstdCompressSync()` 使用 Zstandard 算法压缩 `Uint8Array`。 ```ts theme={null} const buf = Buffer.from("hello".repeat(100)); // 同步 const compressedSync = Bun.zstdCompressSync(buf); // 异步 const compressedAsync = await Bun.zstdCompress(buf); // 带压缩级别（1-22，默认：3） const compressedLevel = Bun.zstdCompressSync(buf, { level: 6 }); ``` ## `Bun.zstdDecompress()` / `Bun.zstdDecompressSync()` 使用 Zstandard 算法解压缩 `Uint8Array`。 ```ts theme={null} const buf = Buffer.from("hello".repeat(100)); const compressed = Bun.zstdCompressSync(buf); // 同步 const decompressedSync = Bun.zstdDecompressSync(compressed); // 异步 const decompressedAsync = await Bun.zstdDecompress(compressed); const dec = new TextDecoder(); dec.decode(decompressedSync); // => "hellohellohello..." ``` *** ## `Bun.inspect()` 将对象序列化为与 `console.log` 打印的完全相同的字符串。 ```ts theme={null} const obj = { foo: "bar" }; const str = Bun.inspect(obj); // => '{\nfoo: "bar" \n}' const arr = new Uint8Array([1, 2, 3]); const str = Bun.inspect(arr); // => "Uint8Array(3) [ 1, 2, 3 ]" ``` ### `Bun.inspect.custom` Bun 用于实现 `Bun.inspect` 的符号。覆盖它以自定义对象打印方式。它与 Node.js 中的 `util.inspect.custom` 相同。 ```ts theme={null} class Foo { [Bun.inspect.custom]() { return "foo"; } } const foo = new Foo(); console.log(foo); // => "foo" ``` ### `Bun.inspect.table(tabularData, properties, options)` 将表格数据格式化为字符串。就像 [`console.table`](https://developer.mozilla.org/en-US/docs/Web/API/console/table_static) 一样，但它返回字符串而不是打印到控制台。 ```ts theme={null} console.log( Bun.inspect.table([ { a: 1, b: 2, c: 3 }, { a: 4, b: 5, c: 6 }, { a: 7, b: 8, c: 9 }, ]), ); // // ┌───┬───┬───┬───┐ // │ │ a │ b │ c │ // ├───┼───┼───┼───┤ // │ 0 │ 1 │ 2 │ 3 │ // │ 1 │ 4 │ 5 │ 6 │ // │ 2 │ 7 │ 8 │ 9 │ // └───┴───┴───┴───┘ ``` 传递属性名称数组以仅显示这些属性。 ```ts theme={null} console.log( Bun.inspect.table( [ { a: 1, b: 2, c: 3 }, { a: 4, b: 5, c: 6 }, ], ["a", "c"], ), ); // // ┌───┬───┬───┐ // │ │ a │ c │ // ├───┼───┼───┤ // │ 0 │ 1 │ 3 │ // │ 1 │ 4 │ 6 │ // └───┴───┴───┘ ``` 传递 `{ colors: true }` 以启用 ANSI 颜色。 ```ts theme={null} console.log( Bun.inspect.table( [ { a: 1, b: 2, c: 3 }, { a: 4, b: 5, c: 6 }, ], { colors: true, }, ), ); ``` *** ## `Bun.nanoseconds()` 返回自当前 `bun` 进程启动以来的纳秒数，类型为 `number`。适用于高精度计时和基准测试。 ```ts theme={null} Bun.nanoseconds(); // => 7288958 ``` *** ## `Bun.readableStreamTo*()` Bun 实现了一组便捷函数，用于异步消费 `ReadableStream` 的主体并将其转换为各种二进制格式。 ```ts theme={null} const stream = (await fetch("https://bun.com")).body; stream; // => ReadableStream await Bun.readableStreamToArrayBuffer(stream); // => ArrayBuffer await Bun.readableStreamToBytes(stream); // => Uint8Array await Bun.readableStreamToBlob(stream); // => Blob await Bun.readableStreamToJSON(stream); // => object await Bun.readableStreamToText(stream); // => string // 以数组形式返回所有数据块 await Bun.readableStreamToArray(stream); // => unknown[] // 以 FormData 对象形式返回所有数据块（编码为 x-www-form-urlencoded） await Bun.readableStreamToFormData(stream); // 以 FormData 对象形式返回所有数据块（编码为 multipart/form-data） await Bun.readableStreamToFormData(stream, multipartFormBoundary); ``` *** ## `Bun.resolveSync()` 使用 Bun 内部的[模块解析](/runtime/module-resolution)算法解析文件路径或模块标识符。第一个参数是要解析的路径，第二个参数是"根"。如果未找到匹配项，则抛出 `Error`。 ```ts theme={null} Bun.resolveSync("./foo.ts", "/path/to/project"); // => "/path/to/project/foo.ts" Bun.resolveSync("zod", "/path/to/project"); // => "/path/to/project/node_modules/zod/index.ts" ``` 要相对于当前工作目录解析，传递 `process.cwd()` 或 `"."` 作为根。 ```ts theme={null} Bun.resolveSync("./foo.ts", process.cwd()); Bun.resolveSync("./foo.ts", "/path/to/project"); ``` 要相对于当前文件所在目录解析，传递 `import.meta.dir`。 ```ts theme={null} Bun.resolveSync("./foo.ts", import.meta.dir); ``` *** ## `Bun.stripANSI()` 比 `strip-ansi` 快约 6-57 倍的替代方案 `Bun.stripANSI(text: string): string` 从字符串中去除 ANSI 转义码。用于移除终端输出中的颜色和格式。 ```ts theme={null} const coloredText = "\u001b[31mHello\u001b[0m \u001b[32mWorld\u001b[0m"; const plainText = Bun.stripANSI(coloredText); console.log(plainText); // => "Hello World" // 适用于各种 ANSI 码 const formatted = "\u001b[1m\u001b[4mBold and underlined\u001b[0m"; console.log(Bun.stripANSI(formatted)); // => "Bold and underlined" ``` `Bun.stripANSI` 比 [`strip-ansi`](https://www.npmjs.com/package/strip-ansi) npm 包更快： ```bash terminal icon="terminal" theme={null} bun bench/snippets/strip-ansi.mjs ``` ```txt theme={null} cpu: Apple M3 Max runtime: bun 1.2.21 (arm64-darwin) benchmark avg (min … max) p75 / p99 ------------------------------------------------------- ---------- Bun.stripANSI 11 chars no-ansi 8.13 ns/iter 8.27 ns (7.45 ns … 33.59 ns) 10.29 ns Bun.stripANSI 13 chars ansi 51.68 ns/iter 52.51 ns (46.16 ns … 113.71 ns) 57.71 ns Bun.stripANSI 16,384 chars long-no-ansi 298.39 ns/iter 305.44 ns (281.50 ns … 331.65 ns) 320.70 ns Bun.stripANSI 212,992 chars long-ansi 227.65 µs/iter 234.50 µs (216.46 µs … 401.92 µs) 262.25 µs ``` ```bash terminal icon="terminal" theme={null} node bench/snippets/strip-ansi.mjs ``` ```txt theme={null} cpu: Apple M3 Max runtime: node 24.6.0 (arm64-darwin) benchmark avg (min … max) p75 / p99 -------------------------------------------------------- --------- npm/strip-ansi 11 chars no-ansi 466.79 ns/iter 468.67 ns (454.08 ns … 570.67 ns) 543.67 ns npm/strip-ansi 13 chars ansi 546.77 ns/iter 550.23 ns (532.74 ns … 651.08 ns) 590.35 ns npm/strip-ansi 16,384 chars long-no-ansi 4.85 µs/iter 4.89 µs (4.71 µs … 5.00 µs) 4.98 µs npm/strip-ansi 212,992 chars long-ansi 1.36 ms/iter 1.38 ms (1.27 ms … 1.73 ms) 1.49 ms ``` *** ## `Bun.wrapAnsi()` `wrap-ansi` npm 包的即插即用替代方案 `Bun.wrapAnsi(input: string, columns: number, options?: WrapAnsiOptions): string` 将文本换行到指定的列宽。它保留 ANSI 转义码和超链接，并正确处理 Unicode/emoji 宽度。这是 [`wrap-ansi`](https://www.npmjs.com/package/wrap-ansi) npm 包的原生替代方案。 ```ts theme={null} // 在 20 列处基本换行 Bun.wrapAnsi("The quick brown fox jumps over the lazy dog", 20); // => "The quick brown fox\njumps over the lazy\ndog" // 保留 ANSI 转义码：打开的样式在每行末尾关闭，并在下一行重新打开， // 使每行单独渲染时显示正确 Bun.wrapAnsi("\u001b[31mThe quick brown fox jumps over the lazy dog\u001b[0m", 20); // => "\u001b[31mThe quick brown fox\u001b[39m\n\u001b[31mjumps over the lazy\u001b[39m\n\u001b[31mdog\u001b[0m" ``` ### 选项 ```ts theme={null} Bun.wrapAnsi("Hello World", 5, { hard: true, // 超过列宽时断开单词（默认：false） wordWrap: true, // 在单词边界处换行（默认：true） trim: true, // 修剪每行首尾的空白（默认：true） ambiguousIsNarrow: true, // 将模糊宽度字符视为窄字符（默认：true） }); ``` | 选项 | 默认 | 描述 | | ------------------- | ------- | -------------------------------------------------------- | | `hard` | `false` | 如果为 `true`，当单词超过列宽时从中间断开单词。 | | `wordWrap` | `true` | 如果为 `true`，在单词边界处换行。如果为 `false`，每行恰好在列宽处断开。 | | `trim` | `true` | 如果为 `true`，修剪每行的首尾空白。 | | `ambiguousIsNarrow` | `true` | 如果为 `true`，将模糊宽度的 Unicode 字符计为 1 列宽。如果为 `false`，计为 2 列宽。 | TypeScript 定义： ```ts expandable theme={null} namespace Bun { export function wrapAnsi( /** * 要换行的字符串 */ input: string, /** * 最大列宽 */ columns: number, /** * 换行选项 */ options?: { /** * 如果为 `true`，当单词在一行中放不下时从中间断开单词。 * 如果为 `false`，仅在单词边界处断开。 * * @default false */ hard?: boolean; /** * 如果为 `true`，尽可能在单词边界处换行。 * 如果为 `false`，每行恰好在列宽处断开（字符 * 在限制位置任意拆分，忽略单词边界）。 * * @default true */ wordWrap?: boolean; /** * 如果为 `true`，修剪每行的首尾空白。 * 如果为 `false`，保留空白。 * * @default true */ trim?: boolean; /** * 当宽度不明确且为 `true` 时，将模糊宽度字符计为 1 个字符宽。 * 如果为 `false`，计为 2 个字符宽。 * * @default true */ ambiguousIsNarrow?: boolean; }, ): string; } ``` *** ## `bun:jsc` 中的 `serialize` 和 `deserialize` 要将 JavaScript 值保存到 SharedArrayBuffer 并恢复，使用 `"bun:jsc"` 模块中的 `serialize` 和 `deserialize`。 ```js theme={null} import { serialize, deserialize } from "bun:jsc"; const buf = serialize({ foo: "bar" }); const obj = deserialize(buf); console.log(obj); // => { foo: "bar" } ``` 在内部，[`structuredClone`](https://developer.mozilla.org/en-US/docs/Web/API/structuredClone) 和 [`postMessage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage) 以相同的方式序列化和反序列化。这将以 SharedArrayBuffer 的形式向 JavaScript 公开底层的 [HTML Structured Clone 算法](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm)。 *** ## `bun:jsc` 中的 `estimateShallowMemoryUsageOf` `estimateShallowMemoryUsageOf` 函数以字节为单位返回对象内存使用的最佳估算值，不包括其属性或其他引用对象的内存使用。要获取精确的按对象内存使用量，请使用 `Bun.generateHeapSnapshot`。 ```js theme={null} import { estimateShallowMemoryUsageOf } from "bun:jsc"; const obj = { foo: "bar" }; const usage = estimateShallowMemoryUsageOf(obj); console.log(usage); // => 16 const buffer = Buffer.alloc(1024 * 1024); estimateShallowMemoryUsageOf(buffer); // => 1048624 const req = new Request("https://bun.com"); estimateShallowMemoryUsageOf(req); // => 167 const array = Array(1024).fill({ a: 1 }); // 数组通常不在内存中连续存储，因此这不会返回有用的值（这不是 bug）。 estimateShallowMemoryUsageOf(array); // => 16 ```