Node.js 兼容性 – 运行时 | Bun 文档

每天，Bun 都越来越接近 100% 的 Node.js API 兼容性。如今，像 Next.js、Express 这样的流行框架以及数百万用于 Node 的 npm 包都能在 Bun 中正常运行。为确保兼容性，我们在 Bun 的每次发布前都会运行 Node.js 测试套件中的数千个测试。

如果一个包在 Node.js 中可以工作，但在 Bun 中不行，我们将 Bun 视为存在 bug。 请提交 issue，我们会修复它。

此页面会定期更新，以反映 Bun 最新版本的兼容性状态。以下信息反映了 Bun 与Node.js v23的兼容性。

内置 Node.js 模块

`node:events`

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

`node:punycode`

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

`node:async_hooks`

🟡 实现了 AsyncLocalStorage 和 AsyncResource。v8 promise hook 不会被调用，并且其使用被强烈反对。

`node:child_process`

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

`node:cluster`

🟡 句柄和文件描述符无法在 worker 之间传递，这意味着目前只有 Linux 支持通过进程（通过 SO_REUSEPORT）进行负载均衡 HTTP 请求。否则，已实现但未经充分测试。

`node:crypto`

🟡 缺少 secureHeapUsed setEngine setFips

`node:http2`

🟡 客户端和服务器已实现（通过 gRPC 的测试套件的 95.25%）。缺少 options.allowHTTP1, options.enableConnectProtocol, ALTSVC 扩展, 以及 http2stream.pushStream。

`node:module`

🟡 缺少 syncBuiltinESMExports, Module#load()。支持覆盖 ESM 和 CJS 模块的 require.cache。module._extensions, module._pathCache, module._cache 为 no-op。module.register 未实现，目前建议使用 Bun.plugin。

`node:util`

🟡 缺少 getCallSite getCallSites getSystemErrorMap getSystemErrorMessage transferableAbortSignal transferableAbortController

`node:v8`

🟡 实现了 writeHeapSnapshot 和 getHeapSnapshot。serialize 和 deserialize 使用 JavaScriptCore 的 wire format 而不是 V8 的。其他方法未实现。用于性能分析，请改用 bun:jsc。

🟡 核心功能和 ES 模块已实现，包括 vm.Script, vm.createContext, vm.runInContext, vm.runInNewContext, vm.runInThisContext, vm.compileFunction, vm.isContext, vm.Module, vm.SourceTextModule, 以及 vm.SyntheticModule 和 importModuleDynamically 支持。timeout 和 breakOnSigint 等选项已完全支持。缺少 vm.measureMemory 和部分 cachedData 功能。

`node:wasi`

🟡 部分实现。

`node:worker_threads`

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

`node:inspector`

🔴 未实现。

`node:repl`

🔴 未实现。

`node:sqlite`

🔴 未实现。

`node:test`

🟡 部分实现。缺少 mocks、snapshots、timers。请改用 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`

🟢 已实现。这是一个包含全局命名空间中所有对象的对象。它很少被直接引用，因为它的内容在没有额外前缀的情况下可用，例如 __dirname 而不是 global.__dirname。

`globalThis`

🟢 别名为 global。

`Headers`

🟢 完全实现。

`MessageChannel`

🟢 完全实现。

`MessageEvent`

🟢 完全实现。

`MessagePort`

🟢 完全实现。

`module`

🟢 完全实现。

`PerformanceEntry`

🟢 完全实现。

`PerformanceMark`

🟢 完全实现。

`PerformanceMeasure`

🟢 完全实现。

`PerformanceObserver`

🟢 完全实现。

`PerformanceObserverEntryList`

🟢 完全实现。

`PerformanceResourceTiming`

🟢 完全实现。

`performance`

🟢 完全实现。

`process`

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