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 链接器

场景	使用	原因
新建单体仓库/工作区	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.js 特有代码前，请查看文档确认对 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 Runtime — 执行文件和脚本，并管理运行时
2. Package Manager — 安装、添加和移除软件包，并管理依赖项
3. Bundler — 为生产环境打包 JavaScript/TypeScript
4. Test Runner — 编写并运行兼容 Jest 的测试
5. bunfig.toml — 配置 Bun 的行为

---

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