Bun 与 Node.js 的关系

很多初学者会把 Bun 理解成「另一个 Node.js」，或者担心「用 Bun 是不是就要抛弃 Node.js 生态」。这一节我们把它讲清楚：Bun 的设计初衷是与 Node.js 高度兼容，让绝大多数 npm 包、框架和既有代码能直接在 Bun 上跑，而不是另起炉灶。

4.1 Bun 不是 Node.js 的 fork

Node.js 是用 C++ 写的运行时，底层使用 V8 引擎。Bun 则是一个独立的运行时实现，最初用 Zig 编写，底层使用 JavaScriptCore（Apple 的 JavaScript 引擎，Safari 同款）。

所以它们的关系是：

• 不是分支（fork）：Bun 没有从 Node.js 源码派生，而是重新实现了一套运行时。
• 是兼容实现：Bun 主动实现 Node.js 的 API、全局对象和内置模块，目标是让为 Node.js 写的代码能「原样」在 Bun 上运行。
• 共享生态：Bun 直接复用 npm registry 上的包、package.json 约定、node: 内置模块等，你的大部分依赖不需要改动。

4.2 兼容性目标与现状

Bun 官网首页写得很直白：Bun aims for 100% Node.js compatibility——注意是 aims（目标），不是 achieved。官方文档维护了一张兼容性对照表，逐项标注内置模块与全局对象的实现状态（🟢 完全实现、🟡 部分实现），并给出各模块在 Node.js 测试套件上的通过率。

从对照表看，大量常用模块已是 🟢 完全实现，例如：

• node:assert、node:buffer、node:console、node:events
• node:fs、node:path、node:url、node:os、node:net、node:stream
• node:events、node:os、node:path、node:url 等模块的测试套件通过率已达 100%

也有一部分属于 🟡 部分实现，例如：

• node:crypto：缺少 setEngine、setFips 等少数接口
• node:worker_threads：部分选项与少量方法未实现
• node:child_process：少数属性（如 proc.gid / proc.uid）与部分 IPC 能力缺失
• node:cluster：跨进程传递句柄仅在特定平台（Linux 通过 SO_REUSEPORT）支持
• node:test：仅部分实现，官方建议直接用 bun test 而非 node:test
• node:inspector：仅 Profiler 相关 API 实现

4.3 Bun 提供的三类 API

在 Bun 运行时里，你能用到三类 API，理解它们的层次有助于写对代码：

1. Web 标准 API：fetch、WebSocket、Response、Request、Headers、ReadableStream 等。这些是浏览器与 Deno、Bun 共享的标准，写前端的人会很熟悉。
2. Node.js 兼容 API：node:fs、node:http、node:path、require()、__dirname 等。这些让既有的 Node.js 生态能直接复用。
3. Bun 原生 API：以 Bun.* 命名空间暴露，例如 Bun.serve()（HTTP 服务器）、Bun.file()、Bun.write()、Bun.spawn()、Bun.$（Shell）等；内置模块则用 bun: 前缀导入，例如 bun:sqlite。这些是 Bun 的「增值能力」，提供比 Node.js 更简洁的封装。

// Web 标准
const res = await fetch("https://example.com");

// Node.js 兼容
import { readFileSync } from "node:fs";
const text = readFileSync("data.txt", "utf8");

// Bun 原生
const server = Bun.serve({ port: 3000, fetch: () => new Response("hi") });

4.4 什么时候适合用 Bun

下面这些场景，引入 Bun 的收益通常比较明显：

• 想用 TypeScript / JSX 但讨厌配置构建链：bun run 免编译直跑，省掉 ts-node、tsx、esbuild 配置。
• 脚本与工具类程序：CLI、构建脚本、数据处理，看重启动速度与简单性。
• HTTP 服务与全栈应用：Bun.serve 内置路由与静态资源，配合热重载开发体验好。
• 测试：bun test 开箱即用，无需额外装 Jest / Vitest。
• 希望「一体化」工具链：运行时、包管理器、测试、打包器统一由 Bun 提供，减少工具碎片。

Bun 在性能上确实有不少亮点：内置转译与运行时层面的优化使启动更快、安装依赖更快。但请理性看待——性能优势主要体现在「工具链开销」（安装、启动、转译、测试）上，业务代码本身的运行速度差异，取决于具体负载，并不一定总是 Bun 胜出。

4.5 什么时候要谨慎

• 强依赖特定原生模块 / Node.js 私有接口：用到 worker_threads 高级选项、child_process 完整能力、特定 C++ 插件或 node:inspector 深度功能时，先验证。
• 生产环境对运行时有严格合规要求：若团队已对 Node.js 的长期支持（LTS）与漏洞响应有成熟流程，切换运行时需要相应的评估与回归测试。
• 依赖某款仅适配 Node.js 的工具：例如某些通过 node 二进制做进程注入、符号链接或特殊 shebang 的工具，需确认 Bun 的 node 兼容模式是否满足。
• 团队学习成本：新工具意味着新踩坑点，评估时要算上团队熟悉度。

4.6 从 Node.js 迁移的思路

如果你打算把现有 Node.js 项目试跑在 Bun 上，推荐渐进式、可逆的路线：

1. 先装 Bun，不删 Node.js：两者可共存，随时回退。
2. 用 Bun 跑现有脚本：bun run 直接执行你的入口文件，看是否能启动。
3. 用 bun install 装依赖：它兼容 package.json，会生成文本锁文件 bun.lock；CI 里加 --frozen-lockfile，锁文件与 package.json 对不上时直接报错，而不是悄悄改锁文件。
4. 逐项替换工具，而非一次性重写：
   • npm run test → bun test
   • node index.js → bun run index.js
   • tsx / ts-node → 直接用 bun run *.ts
5. 问题隔离：若某依赖在 Bun 上报错，先确认是包的问题还是 Bun 兼容问题；前者提 issue 给 Bun，后者提给包维护者或寻找替代。
6. 保留回退能力：在 CI / 生产里先以 Node.js 为主，Bun 作为并行验证，跑稳后再考虑切换默认运行时。

4.7 小结

• Bun 是 兼容 Node.js API 的独立运行时实现，不是 Node.js 的分支；底层用 JavaScriptCore，而非 V8。
• 兼容性在持续逼近 100%，但 🟡 部分实现的模块（如 worker_threads、child_process 细节）仍需实测。
• Bun 里同时有 Web 标准 API、Node.js 兼容 API、Bun 原生 API 三类，可混用。
• 适合：TS/JSX 免编译、脚本工具、HTTP/全栈、测试、一体化工具链；谨慎：深度依赖 Node.js 私有接口或合规要求严格的核心生产系统。
• 迁移走渐进、可逆路线，先并行验证，再决定是否切换默认运行时。