Node.js 兼容性

每一天，Bun 都在更接近 100% 的 Node.js API 兼容性。像 Next.js、Express 等流行框架以及数百万个为 Node.js 设计的 npm 包都可以在 Bun 上运行。为确保兼容性，我们在每次发布 Bun 之前都会运行大量来自 Node.js 测试套件的测试。 如果某个包在 Node.js 中可以工作但在 Bun 中不行，我们认为这是 Bun 的一个 bug。 提交 issue，我们会解决它。此页面会定期更新，反映的是 Bun 与 Node.js v23 兼容性的最新版本。

内置 Node.js 模块

`node:assert`

🟢 完全实现。

`node:buffer`

🟢 完全实现。

`node:console`

🟢 完全实现。

`node:dgram`

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

`node:diagnostics_channel`

🟢 完全实现。

`node:dns`

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

`node:events`

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

`node:fs`

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

`node:http`

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

`node:https`

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

`node:os`

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

`node:path`

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

`node:punycode`

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

`node:querystring`

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

`node:readline`

🟢 完全实现。

`node:stream`

🟢 完全实现。

`node:string_decoder`

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

`node:timers`

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

`node:tty`

🟢 完全实现。

`node:url`

🟢 完全实现。

`node:zlib`

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

`node:async_hooks`

🟡 AsyncLocalStorage 和 AsyncResource 已实现。v8 promise 钩子不会被调用，其使用被强烈不建议。

`node:child_process`

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

`node:cluster`

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

`node:crypto`

🟡 缺少 secureHeapUsed setEngine setFips

`node:domain`

🟡 缺少 Domain active

`node:http2`

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

`node:module`

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

`node:net`

🟢 完全实现。

`node:perf_hooks`

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

`node:process`

🟡 参见 process 全局变量。

`node:sys`

🟡 参见 node:util。

`node:tls`

🟡 缺少 tls.createSecurePair。

`node:util`

🟡 缺少 getCallSite getCallSites getSystemErrorMap getSystemErrorMessage transferableAbortSignal transferableAbortController

`node:v8`

🟡 writeHeapSnapshot 和 getHeapSnapshot 已实现。serialize 和 deserialize 使用 JavaScriptCore 的线格式而非 V8 的。其他方法未实现。性能分析请改用 bun:jsc。

`node:vm`

🟡 核心功能和 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`

🟡 部分实现。

`node:worker_threads`

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

`node:inspector`

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

`node:repl`

🔴 未实现。

`node:sqlite`

🟢 完全实现。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`

🟡 部分实现。进程内 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。

`node:trace_events`

🟢 完全实现。

Node.js 全局变量

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

`AbortController`

🟢 完全实现。

`AbortSignal`

🟢 完全实现。

`Blob`

🟢 完全实现。

`Buffer`

🟢 完全实现。

`ByteLengthQueuingStrategy`

🟢 完全实现。

`__dirname`

🟢 完全实现。

`__filename`

🟢 完全实现。

`atob()`

🟢 完全实现。

`Atomics`

🟢 完全实现。

`BroadcastChannel`

🟢 完全实现。

`btoa()`

🟢 完全实现。

`clearImmediate()`

🟢 完全实现。

`clearInterval()`

🟢 完全实现。

`clearTimeout()`

🟢 完全实现。

`CompressionStream`

🟢 完全实现。

`console`

🟢 完全实现。

`CountQueuingStrategy`

🟢 完全实现。

`Crypto`

🟢 完全实现。

`SubtleCrypto (crypto)`

🟢 完全实现。

`CryptoKey`

🟢 完全实现。

`CustomEvent`

🟢 完全实现。

`DecompressionStream`

🟢 完全实现。

`Event`

🟢 完全实现。

`EventTarget`

🟢 完全实现。

`exports`

🟢 完全实现。

`fetch`

🟢 完全实现。

`FormData`

🟢 完全实现。

`global`

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

`globalThis`

🟢 指向 global。

`Headers`

🟢 完全实现。

`MessageChannel`

🟢 完全实现。

`MessageEvent`

🟢 完全实现。

`MessagePort`

🟢 完全实现。

`module`

🟢 完全实现。

`PerformanceEntry`

🟢 完全实现。

`PerformanceMark`

🟢 完全实现。

`PerformanceMeasure`

🟢 完全实现。

`PerformanceObserver`

🟢 完全实现。

`PerformanceObserverEntryList`

🟢 完全实现。

`PerformanceResourceTiming`

🟢 完全实现。

`performance`

🟢 完全实现。

`process`

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