bun

Bun 技能参考

产品概述

Bun 是一个使用 Zig 编写的一体化 JavaScript 运行时、包管理器、打包器和测试运行器。它用一个快速的二进制文件取代 Node.js、npm、esbuild 和 Jest。关键文件：bunfig.toml（配置）、bun.lock（锁文件）、package.json（项目元数据）。主要命令：bun run、bun install、bun build、bun test。Bun 的启动速度比 Node.js 快 4 倍，安装速度比 npm 快 25 倍。访问 https://bun.com/docs 查看完整文档。

适用场景

以下情况可使用 Bun：

• 运行脚本：无需编译步骤即可直接执行 TypeScript/JavaScript 文件（bun run file.ts）
• 管理依赖项：比 npm/yarn/pnpm 更快地安装、添加、移除或更新包（bun install、bun add）
• 打包代码：使用 bun build 为浏览器或服务器目标构建 JavaScript/TypeScript
• 测试：使用内置测试运行器运行兼容 Jest 的测试（bun test）
• 构建全栈应用：将服务器端和客户端代码打包到单个可执行文件中
• 单体仓库工作流：使用工作区和筛选功能管理多个包
• 替代 Node.js：以更高性能运行任何兼容 Node.js 的代码

以下情况不应使用 Bun：类型检查（请单独使用 tsc）、生成类型声明，或需要原生模块与 Node.js 完全兼容的项目。

快速参考

基本命令

任务	命令	说明
运行 TypeScript 文件	bun run file.ts	即时转译；简写形式可省略 run
运行包脚本	bun run dev	执行 package.json 中的脚本
安装依赖项	bun install	创建 bun.lock 锁文件
添加包	bun add react	添加到 dependencies；开发依赖请使用 -d
移除包	bun remove react	从 package.json 和 node_modules 中移除
运行测试	bun test	自动查找 *.test.ts、*.spec.ts 文件
构建打包文件	bun build ./src/index.ts --outdir ./dist	打包时执行摇树优化；可选择是否压缩
监视模式	bun --watch run file.ts	文件变更时重新运行
创建项目	bun init	使用模板搭建新项目

配置文件：bunfig.toml

位于项目根目录或 ~/.bunfig.toml（全局）。该文件可选，但有助于自定义配置。

[install]
dev = true                    # Install devDependencies
optional = true               # Install optionalDependencies
peer = true                   # Install peerDependencies
linker = "hoisted"           # "hoisted" or "isolated" (pnpm-style)
saveTextLockfile = true      # Use text bun.lock instead of binary

[serve]
port = 3000                  # Default port for Bun.serve()

[test]
root = "."                   # Test root directory
coverage = false             # Enable coverage reporting
timeout = 5000               # Per-test timeout in ms
preload = ["./setup.ts"]     # Scripts to run before tests

[run]
shell = "system"             # "system" or "bun" (Windows defaults to "bun")
bun = true                   # Auto-alias node to bun in scripts

支持的文件类型

Bun 可原生处理：.js、.jsx、.ts、.tsx、.json、.jsonc、.toml、.yaml、.html、.css、.wasm、.node。无需任何配置，直接导入并使用即可。

主要 Bun API

API	用途	示例
Bun.serve()	启动 HTTP 服务器	Bun.serve({ port: 3000, fetch: handler })
Bun.file()	读取/写入文件	await Bun.file("path.txt").text()
Bun.write()	写入磁盘	await Bun.write("out.txt", data)
Bun.build()	打包代码	await Bun.build({ entrypoints, outdir })
Bun.Transpiler	转译代码	new Bun.Transpiler({ loader: "tsx" })
Bun.spawn()	运行子进程	Bun.spawn(["ls", "-la"])

决策指南

何时使用 Hoisted 或 Isolated 链接器

场景	使用	原因
新建 monorepo/工作区	isolated	防止幽灵依赖，隔离更严格
新建单包项目	hoisted	采用传统的 npm 行为，更简单
现有项目（v1.3.2 之前）	hoisted	向后兼容
从 pnpm 迁移	isolated	与 pnpm 的方式一致

在 bunfig.toml 中设置：linker = "isolated"，或通过 CLI 设置：bun install --linker isolated

何时使用 bun build 或 bun run

使用场景	工具	原因
直接执行 TypeScript	bun run	转译速度快，无输出文件
为生产环境做准备	bun build	压缩、摇树优化、打包
发布单个可执行文件	bun build --compile	创建独立二进制文件
开发服务器	bun run + Bun.serve()	热重载，快速迭代

何时在测试中使用 --concurrent

场景	使用 --concurrent	原因
相互独立的异步测试	是	并行执行可加快测试套件运行
使用共享状态的测试	否	对顺序有依赖的测试使用 test.serial()
数据库/API 测试	视情况而定	仅当测试之间不会相互干扰时使用
单元测试	是	通常安全且更快

工作流

1. 初始化项目

bun init my-app
cd my-app

选择模板：Blank、React 或 Library。会创建 package.json、tsconfig.json、.gitignore。

2. 安装依赖

bun install

读取 package.json，下载软件包，并创建 bun.lock。速度远快于 npm。

3. 添加软件包

bun add react
bun add -d @types/react typescript

自动更新 package.json 和 bun.lock。

4. 编写并运行代码

# Create index.ts
echo "console.log('Hello Bun!')" > index.ts

# Run it
bun run index.ts

Bun 会即时转译 TypeScript；无需构建步骤。

5. 创建 HTTP 服务

// server.ts
const server = Bun.serve({
  port: 3000,
  fetch(req) {
    return new Response("Hello!");
  },
});
console.log(`Listening on ${server.url}`);

bun run server.ts

6. 编写测试

// math.test.ts
import { test, expect } from "bun:test";

test("2 + 2 = 4", () => {
  expect(2 + 2).toBe(4);
});

bun test

自动查找并运行所有 *.test.ts 文件。

7. 为生产环境打包

bun build ./src/index.ts --outdir ./dist --minify

将优化后的打包文件输出到 dist/。使用 --target browser|node|bun 控制输出格式。

8. 创建独立可执行文件

bun build ./cli.ts --outfile mycli --compile
./mycli

将代码和 Bun 运行时打包到单个可执行文件中；无需依赖项。

常见注意事项

• 默认禁用生命周期脚本：Bun 出于安全考虑不会运行 postinstall 脚本。将受信任的软件包添加到 package.json 中的 trustedDependencies，即可允许运行这些脚本。
• bun run 与 bun <script>：如果某个内置 Bun 命令与脚本同名，请显式使用 bun run <script> 来运行 package.json 脚本。
• 监视模式标志的位置：使用 bun --watch run file.ts，而不是 bun run file.ts --watch。文件名后面的标志会传递给脚本本身。
• Bun 全局变量的 TypeScript 错误：安装 @types/bun，并在 tsconfig.json 的 compilerOptions 中添加 "lib": ["ESNext"]。
• 锁文件格式：Bun v1.2+ 默认使用文本格式的 bun.lock（而不是二进制格式的 bun.lockb）。请将其提交到版本控制。
• CI 中禁用自动安装：在生产环境中，于 bunfig.toml 中设置 install.auto = "disable"，以防意外下载软件包。
• Node.js 兼容性：Bun 实现了大多数 Node.js API，但并非全部。依赖特定于 Node 的代码之前，请查看文档了解对 node: 模块的支持情况。
• 打包器始终会打包：与 esbuild 不同，bun build 默认始终会打包。使用 Bun.Transpiler 可以转译单个文件而不进行打包。
• 打包器不进行类型检查：bun build 不会进行类型检查。请另外运行 tsc --noEmit 进行类型验证。
• 默认安装对等依赖：与 npm 不同，Bun 会自动安装对等依赖。在 bunfig.toml 中设置 peer = false 即可禁用。

验证清单

使用 Bun 完成工作后，提交之前：

• 运行 bun install，确认依赖项可正常解析且没有错误
• 运行 bun run <script>，测试主入口
• 运行 bun test，确认所有测试均通过
• 运行 bun build，检查 outdir 中是否存在输出文件
• 确认 bun.lock 已提交到版本控制（未被 .gitignore 忽略）
• 检查 bunfig.toml，移除任何不应保留的特定于环境的设置
• 确认没有提交 node_modules 文件夹（应将其列入 .gitignore）
• 如果要构建用于部署，请使用 --production 标志进行测试：bun install --production
• 确认 TypeScript 文件没有类型错误：bun run tsc --noEmit（如果已安装 tsc）
• 检查 ESM 项目的 package.json 是否设置了 "type": "module"

资源

全面导航：https://bun.com/docs/llms.txt — 按页面列出的所有 Bun 文档。

重要页面：

1. Bun 运行时 — 执行文件和脚本，并管理运行时
2. 包管理器 — 安装、添加、移除软件包并管理依赖项
3. 打包器 — 为生产环境打包 JavaScript/TypeScript
4. 测试运行器 — 编写并运行兼容 Jest 的测试
5. bunfig.toml — 配置 Bun 的行为

---

如需更多文档和导航，请参阅：https://bun.com/docs/llms.txt