Bun 全面指南及与 Node.js 深度对比

1. 什么是 Bun

Bun 是一款面向现代 JavaScript 生态的全新运行时，定位为 Node.js 和 Deno 的替代方案，核心目标是提供极致的性能与简洁的开发体验。它并非对现有运行时的简单改进，而是从底层重构，整合了运行时、包管理器、测试工具、打包器等全套开发工具链，旨在解决当前 JavaScript 服务端开发中的性能瓶颈与工具链繁杂问题。

Bun 的核心特性的具体说明如下：

• 极致性能：基于 JavaScriptCore 引擎（而非 V8），配合 Zig 语言编写的底层逻辑，在启动速度、代码执行效率、依赖安装速度上均显著优于传统运行时；

• 完善兼容性：深度兼容 Node.js 生态，支持数百个 Node.js 核心 API（如 fs、path、Buffer）和 npm 包，迁移成本低；

• 全栈工具链集成：内置包管理器、测试运行器、打包器、转译器，无需额外配置即可完成从开发到构建的全流程；

• 现代语法原生支持：默认支持 ES 模块、TypeScript、JSX 等现代语法，无需额外转译工具；

• 浏览器级 Web API：原生提供 fetch、WebSocket、ReadableStream 等浏览器常用 Web API，让服务端与客户端代码编写风格更统一。

目前 Bun 仍处于积极开发阶段，持续迭代新增特性与兼容性优化。

2. 运行时基础概念

"运行时（Runtime）"指程序执行过程中提供的核心支撑环境，包含代码解释引擎、核心库、API 接口等关键组件。对于 JavaScript 而言，运行时的核心作用是解析并执行 JS 代码，并提供语言本身不具备的系统级能力（如文件操作、网络通信、定时器等）。

JavaScript 领域最主流的两大运行时环境如下：

• 浏览器运行时：为客户端 JS 提供环境，核心能力是 DOM 操作、事件响应、浏览器 API 调用，受浏览器安全策略限制；

• Node.js 运行时：为服务端 JS 提供环境，突破浏览器限制，支持文件系统操作、TCP/UDP 通信、进程管理等服务端核心能力。

Bun 作为新一代服务端运行时，核心设计目标有三个：一是极致速度，适配边缘计算等对启动速度敏感的场景；二是简洁 API，提供高度优化的极简 API 集合，降低开发复杂度；三是统一体验，通过集成全套工具链，避免多工具集成的繁琐配置。

3. Node.js 与 Bun 核心区别对比

Bun 以"替代 Node.js"为核心定位，两者在底层设计、性能表现、工具链、生态兼容等维度存在显著差异。以下是详细对比：

对比维度	Node.js	Bun
底层引擎	基于 V8 引擎（Google 开发，用于 Chrome 浏览器），成熟稳定，优化充分。	基于 JavaScriptCore 引擎（Apple 开发，用于 Safari 浏览器），启动速度更快，内存占用更低。
开发语言	核心逻辑基于 C++ 编写，生态插件多依赖 C++ 扩展。	核心逻辑基于 Zig 语言编写，Zig 兼具 C 的性能与更简洁的内存管理，编译速度快。
性能表现	1. 启动速度中等，大型项目冷启动耗时较长；2. 异步 I/O 性能优秀，但在密集计算场景下存在瓶颈；3. npm 依赖安装速度较慢，需依赖第三方工具（如 yarn、pnpm）优化。	1. 启动速度极快，比 Node.js 快 4-5 倍（官方测试数据）；2. 密集计算与异步 I/O 性能均优于 Node.js，JavaScriptCore 引擎在部分场景下执行效率更高；3. 内置包管理器安装依赖速度比 npm 快 10-100 倍，支持并行安装与增量更新。
工具链集成	仅提供基础运行时能力，包管理（npm/yarn）、测试（Jest/Mocha）、打包（Webpack/Rollup）需单独安装配置，工具链分散，配置成本高。	内置全套工具链：1. 包管理器（替代 npm/yarn）；2. 测试运行器（bun:test，兼容 Jest 语法）；3. 打包器（支持 TS/JSX 转译与打包）；4. 转译器（默认支持 TS/JSX，无需额外配置），实现"一站式"开发。
API 支持	1. 核心 API 基于回调函数设计（历史遗留），后新增 Promise 与 async/await 支持；2. 提供丰富的 Node.js 特有 API（如 child_process、cluster）；3. 对 Web API 支持有限，需依赖第三方包（如 node-fetch）。	1. 完全支持 Promise 与 async/await，API 设计更现代，无回调冗余；2. 原生兼容数百个 Node.js 核心 API，迁移无压力；3. 内置浏览器级 Web API（fetch、WebSocket、ReadableStream 等），服务端与客户端代码风格统一；4. 提供 Bun 特有高效 API（如 Bun.serve、Bun.file、Bun.build）。
生态兼容性	生态极度成熟，拥有数百万 npm 包，几乎覆盖所有开发场景；但部分旧包依赖 Node.js 特有 API，兼容性存在差异。	目标兼容所有 Node.js 生态包，目前已支持 90% 以上的常用 npm 包；对于依赖 V8 特有 API 或 C++ 扩展的包，可能存在兼容性问题（持续优化中）。
安全模型	默认无权限限制，程序可直接访问文件系统、网络等资源，安全性需依赖开发者手动控制。	默认禁用依赖包的生命周期脚本（如 preinstall），需手动在 trustedDependencies 中指定可信包；未引入额外权限管理机制，整体安全性略优于 Node.js。
锁文件机制	使用 JSON 格式的 package-lock.json，可读性强，但解析速度较慢。	使用二进制格式的 bun.lockb，解析速度快，占用空间小；支持生成 yarn.lock 以兼容旧项目；可通过 Git 配置实现可读差异对比。
适用场景	1. 大型生产级服务（生态成熟，稳定性有保障）；2. 依赖大量 C++ 扩展的项目；3. 需长期维护的传统项目。	1. 对性能与启动速度敏感的场景（如边缘计算、Serverless 函数）；2. 现代 JS/TS 项目（无需复杂工具链配置）；3. 中小型项目或实验性项目（迁移成本低，开发效率高）。
社区与成熟度	社区庞大，文档丰富，问题解决方案多；版本迭代稳定，兼容性保障强。	社区快速成长中，文档较简洁；版本迭代频繁，新增特性快，但部分边缘场景稳定性仍需验证。

4. Bun 的诞生背景

Bun 的诞生源于现代 JavaScript 生态对"高性能"与"简洁开发体验"的双重需求。随着 JS 应用从简单脚本升级为复杂全栈项目，传统开发工具链的弊端逐渐凸显：Node.js 虽成熟，但底层设计受限于早期架构，无法充分利用现代硬件性能，且工具链分散（需单独配置包管理器、打包器、测试工具），开发与构建效率低下；npm 依赖安装速度慢、锁文件解析繁琐等问题也长期困扰开发者。

Node.js 的局限性主要体现在三个方面：一是 V8 引擎的冷启动速度与内存占用优化空间有限；二是历史遗留的回调 API 增加了开发复杂度；三是工具链分散，配置成本高。为解决这些问题，Deno（由 Node.js 创始人 Ryan Dahl 主导）应运而生，它引入了 TypeScript 原生支持、安全权限模型、Web API 原生支持等现代特性，但由于生态构建周期长、与 Node.js 兼容性不足等原因，未能大规模替代 Node.js。

Bun 作为后起之秀，充分吸收了 Node.js 与 Deno 的经验：一方面坚持兼容 Node.js 生态，降低迁移成本；另一方面通过底层重构（JavaScriptCore + Zig）实现性能突破，同时集成全套工具链，解决开发效率问题。其核心优势在于"兼容现有生态的同时提升性能与开发体验"，这也是它能够快速获得开发者关注的关键。

5. Bun 与 Node.js 性能数据对比

以下性能数据来源于 Bun 官方测试与第三方权威测评（基于相同硬件环境，测试项目为典型服务端应用），供参考：

测试维度	Node.js 18.x	Bun 1.0+	性能提升幅度
冷启动速度（空项目）	~110ms	~25ms	约 4.4 倍
冷启动速度（中型 Express 项目）	~350ms	~60ms	约 5.8 倍
HTTP 服务响应速度（并发 1000）	~1200 QPS	~4500 QPS	约 3.75 倍
npm 依赖安装速度（React 项目，约 150 个依赖）	~65 秒（npm install）	~4 秒（bun install）	约 16 倍
TypeScript 代码转译 + 打包（中型项目）	~28 秒（tsc + webpack）	~2 秒（bun build）	约 14 倍

注：实际性能受项目复杂度、硬件环境、依赖类型影响，以上为平均测试结果。

6. 如何判断是否需要使用 Bun

选择 Bun 还是 Node.js，核心取决于项目需求、团队熟悉度与生态依赖。以下关键因素可帮助决策：

• 性能优先级：若项目是 Serverless 函数、边缘计算服务等对启动速度/响应速度敏感的场景，Bun 是更优选择；若为传统后端服务，Node.js 的成熟度可能更重要。

• 工具链复杂度：若希望简化开发流程，避免配置 Webpack、Jest、npm 等工具，Bun 的内置工具链可大幅提升效率；若团队已熟练掌握 Node.js 工具链，且项目配置稳定，无需迁移。

• 生态依赖兼容性：若项目依赖大量冷门 npm 包或 C++ 扩展，需先通过 Bun 测试兼容性；若仅使用 React、Vue、Express 等主流包，Bun 可无缝兼容。

• 项目规模与阶段：中小型项目、实验性项目可快速迁移至 Bun，享受开发效率提升；大型生产级项目建议先在非核心模块试点，验证稳定性后再逐步迁移。

• 团队技术栈：若团队以现代 JS/TS 为主，且追求简洁开发体验，Bun 更易上手；若团队长期使用 Node.js，且依赖其特有 API（如 cluster），迁移成本较高。

建议决策流程：先在本地搭建 Bun 环境，迁移项目核心模块进行测试，验证兼容性与性能提升后，再根据项目阶段决定是否全量迁移。

7. Bun 安装指南

Bun 支持 macOS、Linux、Windows 三大系统，提供多种安装方式，推荐优先使用包管理器安装（简单高效）：

7.1 macOS

使用 Homebrew 安装（需先安装 Homebrew）：

brew install bun

验证安装：

bun --version

7.2 Windows

推荐使用 Scoop 安装（需先安装 Scoop）：

scoop bucket add extras
scoop install bun

备选方案：从 Bun GitHub 发布页 下载预构建二进制文件，手动添加至系统环境变量。

7.3 Linux

Debian/Ubuntu（APT 包管理器）：

# 下载并执行官方安装脚本
wget -qO- https://bun.sh/install | bash

其他 Linux 发行版：参考官方脚本或下载预构建二进制文件。

7.4 Docker

拉取官方镜像并运行：

# 拉取镜像
docker pull bunsh/bun
# 运行交互式容器
docker run -it bunsh/bun

7.5 手动安装

1. 从 Bun 官方网站 或 GitHub 发布页下载对应系统的预构建二进制文件；2. 解压文件，将二进制文件路径添加至系统环境变量；3. 运行bun --version 验证。

8. Bun CLI 完整指南

Bun 内置 CLI 集成了包管理、运行、测试、打包等核心功能，替代 npm、npx、webpack、jest 等工具，命令简洁直观。以下是完整命令与标志说明：

8.1 核心命令

命令	语法	描述
运行文件	bun run	使用 Bun 运行 JS/TS/JSX 文件，默认支持现代语法，无需转译。
执行脚本	bun lint	运行 package.json 中定义的 lint 脚本（支持所有自定义脚本）。
运行测试	bun test	使用内置测试运行器（bun:test）执行测试用例，兼容 Jest 语法。
执行包二进制	bun x	临时安装并执行 npm 包的 CLI 工具（替代 npx），无需手动安装。
交互式会话	bun repl	启动 Bun 交互式 REPL，支持实时执行 JS/TS 代码。
安装依赖	bun install / bun i	安装 package.json 中的依赖，生成 bun.lockb 锁文件。
添加依赖	bun add / bun a	安装指定依赖并添加至 package.json（--dev 选项添加开发依赖）。
移除依赖	bun remove / bun rm	移除指定依赖并从 package.json 中删除。
更新依赖	bun update	更新指定依赖至最新兼容版本。
链接本地包	bun link []	注册或链接本地 npm 包，方便本地开发调试。
取消链接	bun unlink	注销本地链接的 npm 包。
包管理工具	bun pm	高级包管理操作（如清理缓存、查看依赖树）。
打包构建	bun build	将 TS/JS/JSX 打包为单个文件，支持压缩、代码分割。
初始化项目	bun init	从空白模板创建 Bun 项目，生成 package.json。
从模板创建	bun create / bun c	从官方或社区模板创建项目（如 bun create react）。
升级 Bun	bun upgrade	升级当前 Bun 版本至最新版。
帮助信息	--help	查看指定命令的详细帮助文档。

8.2 常用标志

标志	语法	描述
自动重启	--watch	文件变更时自动重启进程，适用于开发环境。
热重载	--hot	启用热重载，不重启进程即可应用代码变更（支持运行时、测试、打包）。
低内存模式	--smol	减少内存占用，代价是更频繁的垃圾回收。
预加载模块	-r, --preload	在其他模块加载前预加载指定模块（如环境变量配置）。
调试模式	--inspect	激活 Bun 调试器，支持与 Chrome DevTools 连接。
调试等待	--inspect-wait	激活调试器并等待调试工具连接后再执行代码。
断点调试	--inspect-brk	激活调试器，在代码第一行设置断点并等待连接。
忽略缺失入口	--if-present	若脚本入口不存在，直接退出不报错。
禁用自动安装	--no-install	运行时禁用依赖自动安装。
配置自动安装	--install	设置自动安装模式：auto（默认，无 node_modules 时安装）、fallback（缺失包时安装）、force（始终安装）。
自动安装依赖	-i	等同于 --install=fallback，缺失依赖时自动安装。
执行字符串脚本	-e, --eval

9. Bun 核心 API 参考

Bun 提供两类核心 API：一是 Bun 原生 API（挂载在全局 Bun 对象或内置模块），优化性能与开发体验；二是兼容的 Web API，实现服务端与客户端代码统一。以下是分类整理的核心 API：

9.1 Bun 原生 API

主题	核心 API	功能描述
HTTP 服务器	Bun.serve	创建高性能 HTTP/WebSocket 服务器，支持路由、中间件，性能优于 Node.js 的 http 模块。
打包器	Bun.build	内置打包工具，支持 TS/JSX 转译、代码压缩、代码分割，替代 Webpack/Rollup。
文件 I/O	Bun.file、Bun.write	高效文件读写 API，支持异步/同步操作，返回 BunFile 对象（继承 Blob），支持直接解析 JSON、文本。
子进程	Bun.spawn、Bun.spawnSync	创建子进程执行外部命令，性能优于 Node.js 的 child_process 模块。
TCP 连接	Bun.listen、Bun.connect	创建 TCP 服务器/客户端，简化网络通信开发。
转译器	Bun.Transpiler	原生支持 TS/JSX 转译，可自定义转译配置。
路由	Bun.FileSystemRouter	文件系统路由，支持 Next.js 风格路由规则，无需手动配置路由表。
HTML 变换	HTMLRewriter	流式 HTML 解析与修改，适用于服务端渲染场景。
哈希	Bun.hash、Bun.CryptoHasher	高效加密哈希函数，支持多种算法（MD5、SHA-256 等）。
模块元信息	import.meta	提供模块相关元信息（如 import.meta.dir、import.meta.url）。
SQLite	bun:sqlite	内置 SQLite 客户端，无需额外安装依赖，支持同步/异步操作。
外部函数接口	bun:ffi	调用 C/C++ 动态链接库函数，扩展 Bun 能力。
测试	bun:test	内置测试模块，兼容 Jest 断言语法，支持快照测试、异步测试。
Node 兼容	Node-API	支持 Node.js 原生插件，保障生态兼容性。
文件匹配	Bun.Glob	文件路径模式匹配，支持 Glob 语法。
实用工具	Bun.version、Bun.sleep()、Bun.deepEquals() 等	常用工具函数：版本查询、睡眠、深度比较、HTML 转义、流转换等。

9.2 原生支持的 Web API

主题	支持的 API
HTTP 通信	fetch、Response、Request、Headers、AbortController、AbortSignal
URL 处理	URL、URLSearchParams
Web Workers	Worker、self.postMessage、structuredClone、MessagePort、MessageChannel、BroadcastChannel
流处理	ReadableStream、WritableStream、TransformStream、ByteLengthQueuingStrategy、CountQueuingStrategy
二进制数据	Blob
WebSocket	WebSocket
编码解码	atob、btoa、TextEncoder、TextDecoder
JSON 处理	JSON（完整支持）
定时器	setTimeout、clearTimeout、setInterval、clearInterval
加密	crypto、SubtleCrypto、CryptoKey
调试工具	console、performance
微任务	queueMicrotask
错误处理	reportError
用户交互	alert、confirm、prompt（适用于交互式 CLI）
作用域	ShadowRealm
事件系统	EventTarget、Event、ErrorEvent、CloseEvent、MessageEvent

10. Bun 实战示例

以下是 Bun 核心功能的实战示例，覆盖 HTTP 服务、文件操作、测试、打包等常见场景：

10.1 快速创建 HTTP 服务器

// server.ts
const server = Bun.serve({
  port: 3000,
  fetch(request) {
    // 解析请求 URL
    const url = new URL(request.url);
    if (url.pathname === "/") {
      return new Response("Welcome to Bun Server!", { status: 200 });
    }
    return new Response("404 Not Found", { status: 404 });
  },
});

console.log(`Server running on http://localhost:${server.port}`);
// 运行命令：bun run server.ts --watch（文件变更自动重启）

10.2 WebSocket 服务器（带认证）

// websocket-server.js
// 简易 Cookie 解析函数
function parseCookies(cookieStr) {
  if (!cookieStr) return {};
  return cookieStr.split("; ").reduce((cookies, item) => {
    const [key, value] = item.split("=");
    cookies[key] = value;
    return cookies;
  }, {});
}

// 模拟从 Token 获取用户
function getUserFromToken(token) {
  return { id: 1, name: "Test User" }; // 实际场景需对接数据库
}

const server = Bun.serve({
  port: 3001,
  fetch(req, server) {
    const cookies = parseCookies(req.headers.get("Cookie"));
    // 验证 Token 并升级为 WebSocket 连接
    if (cookies["X-Token"]) {
      return server.upgrade(req, {
        data: { authToken: cookies["X-Token"] },
      });
    }
    return new Response("Unauthorized", { status: 401 });
  },
  websocket: {
    // 接收消息处理
    async message(ws, message) {
      console.log(`Received message: ${message}`);
      const user = getUserFromToken(ws.data.authToken);
      // 模拟存储消息（实际对接数据库）
      // await db.Message.insert({ message: String(message), userId: user.id });
      ws.send(`Hello ${user.name}! Your message was received.`);
    },
    // 连接关闭处理
    close(ws) {
      console.log("WebSocket connection closed");
    },
  },
});

console.log(`WebSocket server running on ws://localhost:${server.port}`);

10.3 高效文件读写（JSON 配置修改）

// file-io.ts
// 读取 package.json
const pkgFile = Bun.file(import.meta.dir + "/package.json");
const pkg = await pkgFile.json(); // 直接解析为 JSON 对象

// 修改配置
pkg.name = "bun-demo-project";
pkg.version = "1.0.0";
pkg.description = "A demo project using Bun";

// 写入文件（格式化 JSON）
await Bun.write(pkgFile, JSON.stringify(pkg, null, 2));
console.log("package.json updated successfully!");

10.4 密码哈希与验证（安全加密）

// password.ts
const password = "user-secure-password123";

// 哈希密码（使用 argon2id 算法，默认配置）
const hash = await Bun.password.hash(password);
console.log("Hashed password:", hash); // 输出类似：$argon2id$v=19$m=65536,t=2,p=1$...

// 验证密码
const isMatch = await Bun.password.verify(password, hash);
console.log("Password match:", isMatch); // 输出：true

// 自定义哈希配置（内存、迭代次数等）
const customHash = await Bun.password.hash(password, {
  algorithm: "argon2id",
  memoryCost: 128000, // 内存占用
  timeCost: 3, // 迭代次数
  parallelism: 4, // 并行度
});
console.log("Custom hashed password:", customHash);

10.5 前端项目打包（React/TSX）

// build.ts
const result = await Bun.build({
  entrypoints: ["./src/index.tsx"], // 入口文件
  outdir: "./dist", // 输出目录
  minify: true, // 压缩代码
  sourcemap: "external", // 生成外部 sourcemap（调试用）
  target: "browser", // 目标环境
  plugins: [
    // 若需支持 CSS，可添加 @bun-plugins/css 插件
    // import cssPlugin from "@bun-plugins/css";
    // cssPlugin()
  ],
});

if (!result.success) {
  console.error("Build failed:");
  for (const error of result.errors) {
    console.error(error);
  }
  process.exit(1);
}

console.log("Build completed successfully!");