> ## 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.

# Node.js 兼容性

> Bun 与 Node.js API、模块和全局变量的兼容性状态

每一天，Bun 都在更接近 100% 的 Node.js API 兼容性。像 Next.js、Express 等流行框架以及数百万个为 Node.js 设计的 `npm` 包都可以在 Bun 上运行。为确保兼容性，我们在每次发布 Bun 之前都会运行大量来自 Node.js 测试套件的测试。

**如果某个包在 Node.js 中可以工作但在 Bun 中不行，我们认为这是 Bun 的一个 bug。** [提交 issue](https://bun.com/issues)，我们会解决它。

此页面会定期更新，反映的是 Bun 与 *Node.js v23* 兼容性的最新版本。

## 内置 Node.js 模块

### [`node:assert`](https://nodejs.org/api/assert.html)

🟢 完全实现。

### [`node:buffer`](https://nodejs.org/api/buffer.html)

🟢 完全实现。

### [`node:console`](https://nodejs.org/api/console.html)

🟢 完全实现。

### [`node:dgram`](https://nodejs.org/api/dgram.html)

🟢 完全实现。超过 90% 的 Node.js 测试套件通过。

### [`node:diagnostics_channel`](https://nodejs.org/api/diagnostics_channel.html)

🟢 完全实现。

### [`node:dns`](https://nodejs.org/api/dns.html)

🟢 完全实现。超过 90% 的 Node.js 测试套件通过。

### [`node:events`](https://nodejs.org/api/events.html)

🟢 完全实现。100% 的 Node.js 测试套件通过。`EventEmitterAsyncResource` 底层使用 `AsyncResource`。

### [`node:fs`](https://nodejs.org/api/fs.html)

🟢 完全实现。92% 的 Node.js 测试套件通过。

### [`node:http`](https://nodejs.org/api/http.html)

🟢 完全实现。出站客户端请求体被缓冲而非流式传输。

### [`node:https`](https://nodejs.org/api/https.html)

🟢 API 已实现，但 `Agent` 并非始终被使用。

### [`node:os`](https://nodejs.org/api/os.html)

🟢 完全实现。100% 的 Node.js 测试套件通过。

### [`node:path`](https://nodejs.org/api/path.html)

🟢 完全实现。100% 的 Node.js 测试套件通过。

### [`node:punycode`](https://nodejs.org/api/punycode.html)

🟢 完全实现。100% 的 Node.js 测试套件通过，*已被 Node.js 弃用*。

### [`node:querystring`](https://nodejs.org/api/querystring.html)

🟢 完全实现。100% 的 Node.js 测试套件通过。

### [`node:readline`](https://nodejs.org/api/readline.html)

🟢 完全实现。

### [`node:stream`](https://nodejs.org/api/stream.html)

🟢 完全实现。

### [`node:string_decoder`](https://nodejs.org/api/string_decoder.html)

🟢 完全实现。100% 的 Node.js 测试套件通过。

### [`node:timers`](https://nodejs.org/api/timers.html)

🟢 请改用全局的 `setTimeout` 和相关函数。

### [`node:tty`](https://nodejs.org/api/tty.html)

🟢 完全实现。

### [`node:url`](https://nodejs.org/api/url.html)

🟢 完全实现。

### [`node:zlib`](https://nodejs.org/api/zlib.html)

🟢 完全实现。98% 的 Node.js 测试套件通过。

### [`node:async_hooks`](https://nodejs.org/api/async_hooks.html)

🟡 `AsyncLocalStorage` 和 `AsyncResource` 已实现。v8 promise 钩子不会被调用，其使用被[强烈不建议](https://nodejs.org/docs/latest/api/async_hooks.html#async-hooks)。

### [`node:child_process`](https://nodejs.org/api/child_process.html)

🟡 缺少 `proc.gid` `proc.uid`。`Stream` 类未导出。IPC 无法发送套接字句柄。Node.js ↔ Bun IPC 可以使用 JSON 序列化。

### [`node:cluster`](https://nodejs.org/api/cluster.html)

🟡 句柄和文件描述符无法在工作进程之间传递，因此跨进程的 HTTP 请求负载均衡仅支持 Linux（通过 `SO_REUSEPORT`）。除此之外已实现，但未经实战充分测试。

### [`node:crypto`](https://nodejs.org/api/crypto.html)

🟡 缺少 `secureHeapUsed` `setEngine` `setFips`

### [`node:domain`](https://nodejs.org/api/domain.html)

🟡 缺少 `Domain` `active`

### [`node:http2`](https://nodejs.org/api/http2.html)

🟡 客户端和服务端已实现（gRPC 测试套件 95.25% 通过）。

### [`node:module`](https://nodejs.org/api/module.html)

🟡 缺少 `syncBuiltinESMExports`、`Module#load()`。支持通过 `require.cache` 覆盖 ESM 和 CJS 模块。`module._extensions`、`module._pathCache`、`module._cache` 是空操作。`module.register` 未实现；推荐使用 [`Bun.plugin`](/runtime/plugins) 替代。

### [`node:net`](https://nodejs.org/api/net.html)

🟢 完全实现。

### [`node:perf_hooks`](https://nodejs.org/api/perf_hooks.html)

🟡 API 已实现，但该模块的 Node.js 测试套件未通过。

### [`node:process`](https://nodejs.org/api/process.html)

🟡 参见 [`process`](#process) 全局变量。

### [`node:sys`](https://nodejs.org/api/util.html)

🟡 参见 [`node:util`](#node-util)。

### [`node:tls`](https://nodejs.org/api/tls.html)

🟡 缺少 `tls.createSecurePair`。

### [`node:util`](https://nodejs.org/api/util.html)

🟡 缺少 `getCallSite` `getCallSites` `getSystemErrorMap` `getSystemErrorMessage` `transferableAbortSignal` `transferableAbortController`

### [`node:v8`](https://nodejs.org/api/v8.html)

🟡 `writeHeapSnapshot` 和 `getHeapSnapshot` 已实现。`serialize` 和 `deserialize` 使用 JavaScriptCore 的线格式而非 V8 的。其他方法未实现。性能分析请改用 [`bun:jsc`](/project/benchmarking#javascript-heap-stats)。

### [`node:vm`](https://nodejs.org/api/vm.html)

🟡 核心功能和 ES 模块已实现，包括 `vm.Script`、`vm.createContext`、`vm.runInContext`、`vm.runInNewContext`、`vm.runInThisContext`、`vm.compileFunction`、`vm.isContext`、`vm.Module`、`vm.SourceTextModule`、`vm.SyntheticModule` 和 `importModuleDynamically` 支持。`timeout` 和 `breakOnSigint` 等选项完全支持。

### [`node:wasi`](https://nodejs.org/api/wasi.html)

🟡 部分实现。

### [`node:worker_threads`](https://nodejs.org/api/worker_threads.html)

🟡 `Worker` 不支持以下选项：`stdin` `stdout` `stderr` `trackedUnmanagedFds` `resourceLimits`。缺少 `markAsUntransferable` `moveMessagePortToContext`。

### [`node:inspector`](https://nodejs.org/api/inspector.html)

🟡 部分实现。`Profiler` API 受支持（`Profiler.enable`、`Profiler.disable`、`Profiler.start`、`Profiler.stop`、`Profiler.setSamplingInterval`）。其他 inspector API 未实现。

### [`node:repl`](https://nodejs.org/api/repl.html)

🔴 未实现。

### [`node:sqlite`](https://nodejs.org/api/sqlite.html)

🟢 完全实现。`backup()` 同步运行并阻塞事件循环（Node 在工作线程上运行）。`Buffer`/`Uint8Array` 数据库路径必须是有效的 UTF-8（Node 直接传递原始字节；Bun 拒绝非 UTF-8 并返回 `ERR_INVALID_ARG_VALUE`）。在 macOS 上，Bun 使用系统的 `libsqlite3.dylib`；`loadExtension()`（以及在较旧 macOS 版本上的 `createSession()`/`applyChangeset()`）需要完整的 SQLite 构建——在打开数据库之前调用 `require("bun:sqlite").Database.setCustomSQLite(path)`。

### [`node:test`](https://nodejs.org/api/test.html)

🟡 部分实现。进程内 API 在测试文件以 `bun test` 运行时可以工作：测试、套件、子测试、钩子、`t.plan()`、`t.assert`、`assert.register()`、`t.waitFor()`、`getTestContext()` 和 `t.mock`（函数/方法/getter/setter/属性模拟和模拟定时器）。缺少 `run()`、`node:test/reporters`、快照测试、`mock.module()`、代码覆盖率、`--test-only`、测试级 `signal`/`t.signal` 中止以及 Node 的 `--test` CLI 运行器模式。`test.only()` / `{only: true}` 被接受但不进行过滤。`concurrency` 被验证但子测试始终串行运行。请改用 [`bun:test`](/test)。

### [`node:trace_events`](https://nodejs.org/api/tracing.html)

🟢 完全实现。

## Node.js 全局变量

以下列表涵盖 Node.js 实现的每个全局变量以及 Bun 的兼容性状态。

### [`AbortController`](https://developer.mozilla.org/zh-CN/docs/Web/API/AbortController)

🟢 完全实现。

### [`AbortSignal`](https://developer.mozilla.org/zh-CN/docs/Web/API/AbortSignal)

🟢 完全实现。

### [`Blob`](https://developer.mozilla.org/zh-CN/docs/Web/API/Blob)

🟢 完全实现。

### [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer)

🟢 完全实现。

### [`ByteLengthQueuingStrategy`](https://developer.mozilla.org/zh-CN/docs/Web/API/ByteLengthQueuingStrategy)

🟢 完全实现。

### [`__dirname`](https://nodejs.org/api/globals.html#__dirname)

🟢 完全实现。

### [`__filename`](https://nodejs.org/api/globals.html#__filename)

🟢 完全实现。

### [`atob()`](https://developer.mozilla.org/zh-CN/docs/Web/API/atob)

🟢 完全实现。

### [`Atomics`](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Atomics)

🟢 完全实现。

### [`BroadcastChannel`](https://developer.mozilla.org/zh-CN/docs/Web/API/BroadcastChannel)

🟢 完全实现。

### [`btoa()`](https://developer.mozilla.org/zh-CN/docs/Web/API/btoa)

🟢 完全实现。

### [`clearImmediate()`](https://developer.mozilla.org/zh-CN/docs/Web/API/Window/clearImmediate)

🟢 完全实现。

### [`clearInterval()`](https://developer.mozilla.org/zh-CN/docs/Web/API/Window/clearInterval)

🟢 完全实现。

### [`clearTimeout()`](https://developer.mozilla.org/zh-CN/docs/Web/API/Window/clearTimeout)

🟢 完全实现。

### [`CompressionStream`](https://developer.mozilla.org/zh-CN/docs/Web/API/CompressionStream)

🟢 完全实现。

### [`console`](https://developer.mozilla.org/zh-CN/docs/Web/API/console)

🟢 完全实现。

### [`CountQueuingStrategy`](https://developer.mozilla.org/zh-CN/docs/Web/API/CountQueuingStrategy)

🟢 完全实现。

### [`Crypto`](https://developer.mozilla.org/zh-CN/docs/Web/API/Crypto)

🟢 完全实现。

### [`SubtleCrypto (crypto)`](https://developer.mozilla.org/zh-CN/docs/Web/API/crypto)

🟢 完全实现。

### [`CryptoKey`](https://developer.mozilla.org/zh-CN/docs/Web/API/CryptoKey)

🟢 完全实现。

### [`CustomEvent`](https://developer.mozilla.org/zh-CN/docs/Web/API/CustomEvent)

🟢 完全实现。

### [`DecompressionStream`](https://developer.mozilla.org/zh-CN/docs/Web/API/DecompressionStream)

🟢 完全实现。

### [`Event`](https://developer.mozilla.org/zh-CN/docs/Web/API/Event)

🟢 完全实现。

### [`EventTarget`](https://developer.mozilla.org/zh-CN/docs/Web/API/EventTarget)

🟢 完全实现。

### [`exports`](https://nodejs.org/api/globals.html#exports)

🟢 完全实现。

### [`fetch`](https://developer.mozilla.org/zh-CN/docs/Web/API/fetch)

🟢 完全实现。

### [`FormData`](https://developer.mozilla.org/zh-CN/docs/Web/API/FormData)

🟢 完全实现。

### [`global`](https://nodejs.org/api/globals.html#global)

🟢 已实现。`global` 是一个包含全局命名空间中所有对象的对象。很少直接引用，因为其内容无需前缀即可使用，例如 `__dirname` 而非 `global.__dirname`。

### [`globalThis`](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/globalThis)

🟢 指向 `global`。

### [`Headers`](https://developer.mozilla.org/zh-CN/docs/Web/API/Headers)

🟢 完全实现。

### [`MessageChannel`](https://developer.mozilla.org/zh-CN/docs/Web/API/MessageChannel)

🟢 完全实现。

### [`MessageEvent`](https://developer.mozilla.org/zh-CN/docs/Web/API/MessageEvent)

🟢 完全实现。

### [`MessagePort`](https://developer.mozilla.org/zh-CN/docs/Web/API/MessagePort)

🟢 完全实现。

### [`module`](https://nodejs.org/api/globals.html#module)

🟢 完全实现。

### [`PerformanceEntry`](https://developer.mozilla.org/zh-CN/docs/Web/API/PerformanceEntry)

🟢 完全实现。

### [`PerformanceMark`](https://developer.mozilla.org/zh-CN/docs/Web/API/PerformanceMark)

🟢 完全实现。

### [`PerformanceMeasure`](https://developer.mozilla.org/zh-CN/docs/Web/API/PerformanceMeasure)

🟢 完全实现。

### [`PerformanceObserver`](https://developer.mozilla.org/zh-CN/docs/Web/API/PerformanceObserver)

🟢 完全实现。

### [`PerformanceObserverEntryList`](https://developer.mozilla.org/zh-CN/docs/Web/API/PerformanceObserverEntryList)

🟢 完全实现。

### [`PerformanceResourceTiming`](https://developer.mozilla.org/zh-CN/docs/Web/API/PerformanceResourceTiming)

🟢 完全实现。

### [`performance`](https://developer.mozilla.org/zh-CN/docs/Web/API/performance)

🟢 完全实现。

### [`process`](https://nodejs.org/api/process.html)

🟡 基本实现。`process.binding`（某些包依赖的内部 Node.js 绑定）部分实现。在 macOS 和 Linux 上 `process.title` 是空操作。`getActiveResourcesInfo` `setActiveResourcesInfo`、`getActiveResources` 和 `setSourceMapsEnabled` 是存根。较新的 API 如 `process.loadEnvFile` 未实现。

### [`queueMicrotask()`](https://developer.mozilla.org/zh-CN/docs/Web/API/queueMicrotask)

🟢 完全实现。

### [`ReadableByteStreamController`](https://developer.mozilla.org/zh-CN/docs/Web/API/ReadableByteStreamController)

🟢 完全实现。

### [`ReadableStream`](https://developer.mozilla.org/zh-CN/docs/Web/API/ReadableStream)

🟢 完全实现。

### [`ReadableStreamBYOBReader`](https://developer.mozilla.org/zh-CN/docs/Web/API/ReadableStreamBYOBReader)

🟢 完全实现。

### [`ReadableStreamBYOBRequest`](https://developer.mozilla.org/zh-CN/docs/Web/API/ReadableStreamBYOBRequest)

🟢 完全实现。

### [`ReadableStreamDefaultController`](https://developer.mozilla.org/zh-CN/docs/Web/API/ReadableStreamDefaultController)

🟢 完全实现。

### [`ReadableStreamDefaultReader`](https://developer.mozilla.org/zh-CN/docs/Web/API/ReadableStreamDefaultReader)

🟢 完全实现。

### [`require()`](https://nodejs.org/api/globals.html#require)

🟢 完全实现，包括 [`require.main`](https://nodejs.org/api/modules.html#requiremain)、[`require.cache`](https://nodejs.org/api/modules.html#requirecache)、[`require.resolve`](https://nodejs.org/api/modules.html#requireresolverequest-options)。

### [`Response`](https://developer.mozilla.org/zh-CN/docs/Web/API/Response)

🟢 完全实现。

### [`Request`](https://developer.mozilla.org/zh-CN/docs/Web/API/Request)

🟢 完全实现。

### [`setImmediate()`](https://developer.mozilla.org/zh-CN/docs/Web/API/Window/setImmediate)

🟢 完全实现。

### [`setInterval()`](https://developer.mozilla.org/zh-CN/docs/Web/API/Window/setInterval)

🟢 完全实现。

### [`setTimeout()`](https://developer.mozilla.org/zh-CN/docs/Web/API/Window/setTimeout)

🟢 完全实现。

### [`structuredClone()`](https://developer.mozilla.org/zh-CN/docs/Web/API/structuredClone)

🟢 完全实现。

### [`SubtleCrypto`](https://developer.mozilla.org/zh-CN/docs/Web/API/SubtleCrypto)

🟢 完全实现。

### [`DOMException`](https://developer.mozilla.org/zh-CN/docs/Web/API/DOMException)

🟢 完全实现。

### [`TextDecoder`](https://developer.mozilla.org/zh-CN/docs/Web/API/TextDecoder)

🟢 完全实现。

### [`TextDecoderStream`](https://developer.mozilla.org/zh-CN/docs/Web/API/TextDecoderStream)

🟢 完全实现。

### [`TextEncoder`](https://developer.mozilla.org/zh-CN/docs/Web/API/TextEncoder)

🟢 完全实现。

### [`TextEncoderStream`](https://developer.mozilla.org/zh-CN/docs/Web/API/TextEncoderStream)

🟢 完全实现。

### [`TransformStream`](https://developer.mozilla.org/zh-CN/docs/Web/API/TransformStream)

🟢 完全实现。

### [`TransformStreamDefaultController`](https://developer.mozilla.org/zh-CN/docs/Web/API/TransformStreamDefaultController)

🟢 完全实现。

### [`URL`](https://developer.mozilla.org/zh-CN/docs/Web/API/URL)

🟢 完全实现。

### [`URLSearchParams`](https://developer.mozilla.org/zh-CN/docs/Web/API/URLSearchParams)

🟢 完全实现。

### [`WebAssembly`](https://nodejs.org/api/globals.html#webassembly)

🟢 完全实现。

### [`WritableStream`](https://developer.mozilla.org/zh-CN/docs/Web/API/WritableStream)

🟢 完全实现。

### [`WritableStreamDefaultController`](https://developer.mozilla.org/zh-CN/docs/Web/API/WritableStreamDefaultController)

🟢 完全实现。

### [`WritableStreamDefaultWriter`](https://developer.mozilla.org/zh-CN/docs/Web/API/WritableStreamDefaultWriter)

🟢 完全实现。