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

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

如果一个包在 Node.js 中可以工作，但在 Bun 中无法工作，我们将其视为 Bun 中的一个错误。 请提交 issue，我们会修复它。

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

内置 Node.js 模块

`node:events`

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

`node:punycode`

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

`node:async_hooks`

🟡 AsyncLocalStorage 和 AsyncResource 已实现。 v8 promise hooks 不会被调用，并且强烈建议不要使用。

`node:child_process`

🟡 缺少 proc.gid proc.uid。 Stream 类未导出。 IPC 无法发送 socket 句柄。 Node.js <> Bun IPC 可以与 JSON 序列化一起使用。

`node:cluster`

🟡 句柄和文件描述符无法在 worker 之间传递，这意味着跨进程的 HTTP 请求负载均衡目前仅在 Linux 上受支持（通过 SO_REUSEPORT）。其他方面已实现，但未经实战检验。

`node:crypto`

🟡 缺少 ECDH checkPrime checkPrimeSync generatePrime generatePrimeSync hkdf hkdfSync secureHeapUsed setEngine setFips

某些方法尚未优化。

`node:http2`

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

🟡 缺少 runMain syncBuiltinESMExports, Module#load()。支持覆盖 ESM 和 CJS 模块的 require.cache。 module._extensions、module._pathCache、module._cache 是空操作。 module.register 未实现，我们建议在此期间使用 Bun.plugin。

`node:net`

🟡 SocketAddress 类未公开（但已实现）。 BlockList 存在但为空操作。

`node:perf_hooks`

🟡 缺少 createHistogram monitorEventLoopDelay。建议使用全局 performance 而不是 perf_hooks.performance。

`node:process`

🟡 请参阅 process 全局对象。

`node:sys`

🟡 请参阅 node:util。

`node:tls`

🟡 缺少 tls.createSecurePair。

`node:util`

🟡 缺少 getCallSite getCallSites getSystemErrorMap getSystemErrorMessage transferableAbortSignal transferableAbortController MIMEType MIMEParams

`node:v8`

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

`node:vm`

🟡 核心功能工作正常，但实验性的 VM ES 模块未实现，包括 vm.Module、vm.SourceTextModule、vm.SyntheticModule、importModuleDynamically 和 vm.measureMemory。诸如 timeout、breakOnSigint、cachedData 等选项尚未实现。

`node:wasi`

🟡 部分实现。

`node:worker_threads`

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

`node:inspector`

🔴 未实现。

`node:repl`

🔴 未实现。

`node:sqlite`

🔴 未实现。

`node:test`

🔴 未实现。请改用 bun:test。

`node:trace_events`

🔴 未实现。

Node.js 全局对象

下表列出了 Node.js 和 Bun 当前兼容性状态实现的所有全局对象。

`AbortController`

🟢 完全实现。

`AbortSignal`

🟢 完全实现。

`Blob`

🟢 完全实现。

`Buffer`

🟢 完全实现。

`ByteLengthQueuingStrategy`

🟢 完全实现。

`__dirname`

🟢 完全实现。

`__filename`

🟢 完全实现。

`atob()`

🟢 完全实现。

`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 尚未实现。