在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

oven-sh/bun

菜单

Node.js 兼容性

相关源文件

Bun 通过 JavaScript 重写核心模块、内置全局对象以及连接 Node.js 模式与 Bun 运行时架构的兼容层，实现了全面的 Node.js API 兼容性。这种兼容性使得大多数 Node.js 应用程序能够以最少的或无需代码更改即可在 Bun 上运行。

概述

Bun 的 Node.js 兼容性通过以下几个关键机制实现：

  1. 对 Node.js 核心模块（如 node:fs、node:http、node:events 等）的JavaScript 重写。
  2. 兼容类型和实用程序，用于连接 Node.js 模式与 Bun 的内部 API。
  3. 对 Node.js 特定全局变量（如 process、Buffer 和 global）的全局对象模拟。
  4. API 兼容接口，利用 Bun 的性能优化，同时保持 Node.js 的语义。
  5. 跨平台抽象，透明地处理平台差异。

兼容层旨在提供高保真的 Node.js 行为模拟，同时利用 Bun 的性能特性。

架构

Node.js 兼容层架构

核心兼容类型实现

来源： src/bun.js/node/types.zig17-328 src/js/node/fs.ts1-42 src/js/node/http.ts1-72

核心兼容类型

Bun 实现了全面的 Node.js 兼容类型系统，用于处理 Node.js API 模式与 Bun 内部表示之间的转换。

字符串和 Buffer 类型处理

Node.js 类型Bun 实现目的
StringOrBufferbun.SliceWithUnderlyingString高效处理字符串和 Buffer 对象
BlobOrStringOrBufferbun.SliceWithUnderlyingString 和 JSC.WebCore.Blob 的联合支持 Blob 对象的扩展类型
PathLike带有 Buffer/URL 支持的 bun.PathString跨平台路径处理
编码枚举，映射到 Bun 的编码系统文本编码兼容性

路径和文件描述符处理

来源： src/bun.js/node/types.zig483-922 src/bun.js/node/types.zig137-328 src/js/node/http.ts1-72

核心模块实现

Bun 提供了 Node.js 核心模块的 JavaScript 重写，在保持 API 兼容性的同时利用了 Bun 的性能优化。

文件系统模块

node:fs 模块是 Bun 中最全面的兼容性实现之一。

文件系统操作架构

关键 FS 实现细节

功能实现位置
异步操作带有 JSC.WorkPoolTask 的线程池src/bun.js/node/node_fs.zig338-444
路径验证带有跨平台处理的 PathLike.fromJS()src/bun.js/node/types.zig636-734
错误处理sys.Error 到 JSC.SystemError 的转换src/sys.zig323-623
编码支持Encoding 枚举，支持 utf8、base64、hex 等。src/bun.js/node/types.zig333-474
Windows 支持平台特定路径规范化src/bun.js/node/types.zig565-634

HTTP 模块

Bun 的 HTTP 模块在 Node.js 的事件驱动 API 与 Bun 的 fetch API 之间架起了桥梁。

HTTP 事件和 Socket 模拟

HTTP 实现包括复杂的 Socket 模拟，以弥合 Node.js 的基于 Socket 的模型与 Bun 的基于 Fetch 的架构之间的差距。

Events 模块

node:events 模块提供了 Node.js 中广泛使用的基础 EventEmitter 模式。

模块实现状态

模块状态主要功能实现位置
node:fs🟢 完全实现异步/同步操作、流、监听器src/js/node/fs.ts
node:http🟢 完全实现服务器、客户端、代理、WebSocket 升级src/js/node/http.ts
node:events🟢 完全实现EventEmitter、异步迭代器、捕获拒绝src/js/node/events.ts
node:stream🟢 完全实现Readable、Writable、Transform、pipelinesrc/js/node/stream.ts
node:buffer🟢 完全实现Buffer 类、编码/解码内置全局
node:path🟢 完全实现跨平台路径操作内置
node:crypto🟡 大部分实现Hash、HMAC、加密、缺少部分高级功能内置
node:process🟡 大部分实现基本 process 对象，缺少部分高级功能内置全局

来源： src/js/node/fs.ts1-1715 src/js/node/http.ts1-72 src/js/node/events.ts1-713 src/bun.js/node/node_fs_binding.zig89-206

兼容性机制

跨平台抽象

Bun 实现了全面的跨平台抽象，以确保 Node.js 兼容性在不同操作系统上的一致性。

错误处理兼容性

Bun 提供了全面的错误兼容性，以匹配 Node.js 的错误模式。

错误类型Node.js 模式Bun 实现
SystemError具有 code、errno、syscall、path 属性sys.Error.toSystemError() 转换
ValidationErrorERR_INVALID_ARG_TYPE、ERR_INVALID_ARG_VALUE带有兼容消息的内置验证器
FileSystemError特定于路径的错误消息路径信息通过错误链保留
NetworkErrorSocket 和 HTTP 特定错误从 Bun 的 fetch/WebSocket 错误映射而来

异步兼容模式

来源： src/sys.zig323-623 src/bun.js/node/types.zig736-786 src/bun.js/node/node_fs.zig338-444

Node.js 兼容性最佳实践

为了最大程度地在 Bun 中运行 Node.js 代码的兼容性：

  1. 优先使用内置的 Node.js 核心模块，而不是第三方替代品。
  2. 在将应用程序从 Node.js 迁移到 Bun 时，进行彻底的测试。
  3. 对于原生模块，优先选择使用 N-API 的，而不是直接集成 V8 的。
  4. 注意性能差异，尤其是在 I/O 操作方面。
  5. 迁移前检查关键依赖项的兼容性。

WebSocket 支持

Bun 通过连接 Bun 的 WebSocket 实现与 Node.js 的基于事件的模式，实现了 Node.js 兼容的 WebSocket 支持。

来源： src/bun.js/api/server/NodeHTTPResponse.zig121-206

未来发展

Bun 将在每个版本中继续扩展和改进其 Node.js 兼容性。持续的开发领域包括：

  1. 扩展对更多 Node.js 模块的支持
  2. 提高兼容层性能
  3. 为不支持的功能提供更好的错误消息

来源： test/js/node/http/node-http.test.ts test/napi/napi.test.ts