Bun 是一款用 Zig 语言编写的全能 JavaScript 工具链，集运行时、包管理器、构建器、测试器于一体。它的包管理器速度比 npm 快 25 倍以上，是目前最快的 JavaScript 包管理解决方案。
🎯 环境说明：本文基于 Bun v1.2.x 编写。
Bun 是什么
Bun 不仅是包管理器，它是完整的 JavaScript/TypeScript 工具链：
| 功能 | 说明 |
|---|---|
| 运行时 | 替代 Node.js，原生支持 TypeScript |
| 包管理器 | 替代 npm/yarn/pnpm |
| 打包器 | 替代 webpack/esbuild/parcel |
| 测试运行器 | 替代 Jest/Vitest |
本文主要聚焦于 Bun 作为包管理器的使用。
为什么选择 Bun
极致的速度
Bun 的包管理器使用原生代码实现，利用系统级 API 和硬链接技术：
| 操作 | npm | pnpm | Bun |
|---|---|---|---|
| 安装（无缓存） | 25.6s | 14.2s | 1.1s |
| 安装（有缓存） | 5.2s | 1.8s | 0.3s |
数据基于典型中型项目，实际速度因项目而异
兼容性
✅ Bun 高度兼容 Node.js 生态：
- 支持
package.json - 支持
node_modules - 支持绝大多数 npm 包
- 支持 CommonJS 和 ESM
- 内置 Node.js API 兼容层
开箱即用
✅ 无需配置即可运行 TypeScript、JSX：
$ bun run index.ts # 直接运行 TypeScript$ bun run App.tsx # 直接运行 TSX安装 Bun
macOS / Linux
$ curl -fsSL https://bun.sh/install | bashmacOS（Homebrew）
$ brew install oven-sh/bun/bunWindows
> powershell -c "irm bun.sh/install.ps1 | iex"或使用 Scoop：
> scoop install bun验证安装：
$ bun --version1.1.38升级 Bun
$ bun upgrade项目初始化
$ mkdir my-project && cd my-project$ bun init交互式创建 package.json，或使用 -y 跳过：
$ bun init -yBun 会生成 package.json 和 tsconfig.json（如果是 TypeScript 项目）。
依赖管理
安装依赖
# 安装 package.json 中的所有依赖$ bun install# 或简写$ bun i
# 安装指定包$ bun add lodash
# 安装开发依赖$ bun add -d typescript# 或$ bun add --dev typescript
# 安装指定版本$ bun add lodash@4.17.21
# 全局安装$ bun add -g typescript移除依赖
$ bun remove lodash
# 全局移除$ bun remove -g typescript更新依赖
# 更新指定包$ bun update lodash
# 更新所有包$ bun update
# 交互式更新$ bun update -i
# 递归更新所有 workspace$ bun update -r
# 交互式递归更新（Monorepo 推荐）$ bun update -i -rbun.lockb
Bun 使用二进制格式的 bun.lockb 作为 lockfile，比 JSON/YAML 格式更紧凑、解析更快。
# 查看 lockfile 内容（转为 yarn.lock 格式）$ bun bun.lockb若需要与非 Bun 环境兼容，可生成 yarn.lock：
$ bun install --yarn运行脚本
# 运行 package.json 中的脚本$ bun run dev$ bun run build
# 简写（无同名文件时）$ bun dev$ bun build
# 传递参数$ bun run test --watch直接运行文件
Bun 可直接运行 JavaScript/TypeScript 文件：
$ bun run index.ts$ bun run script.js
# 简写$ bun index.tsbunx - 执行包命令
类似 npx，临时下载并执行包：
$ bunx create-react-app my-app$ bunx cowsay "Hello Bun!"
# 执行本地包$ bunx eslint srcWorkspaces
Bun 支持 npm/yarn 风格的 workspaces：
{ "name": "my-monorepo", "private": true, "workspaces": ["packages/*", "apps/*"]}支持 glob 排除模式：
{ "workspaces": ["packages/**", "!packages/**/test/**"]}在 monorepo 中安装依赖：
$ bun installBun 会解析所有 workspace 的依赖并统一安装。
workspace 协议
使用 workspace: 协议引用本地包：
{ "name": "pkg-a", "dependencies": { "pkg-b": "workspace:*" }}| 协议 | 发布时转换 |
|---|---|
workspace:* | 当前版本，如 1.2.3 |
workspace:^ | ^1.2.3 |
workspace:~ | ~1.2.3 |
过滤安装
使用 --filter 选择性安装：
# 只安装指定 workspace 的依赖$ bun install --filter pkg-a
# 使用路径$ bun install --filter "./packages/pkg-a"
# 通配符匹配$ bun install --filter "pkg-*"
# 排除指定包$ bun install --filter "!pkg-c"
# 组合使用$ bun install --filter "pkg-*" --filter "!pkg-c"Workspace 命令
# 在指定 workspace 执行命令$ bun run --filter @my-monorepo/web dev
# 添加依赖到指定 workspace$ bun add react --filter @my-monorepo/web配置
bunfig.toml
Bun 使用 bunfig.toml 作为配置文件：
# 设置 npm 源[install]registry = "https://registry.npmmirror.com"
# 缓存目录cache = "~/.bun/install/cache"
# 生产模式（不安装 devDependencies）production = false
# 冻结 lockfilefrozen-lockfile = false常用配置项
[install]# npm 源registry = "https://registry.npmmirror.com"
# scope 私有源[install.scopes]"@company" = "https://npm.company.com/"
# 信任特定包的安装脚本[install.trustedDependencies]my-package = true与 Node.js 兼容性
Bun 实现了大部分 Node.js API，但仍有差异：
已支持
fs、path、os等核心模块process、Buffer、consolehttp、https（基础功能）- CommonJS 和 ESM
- 大多数 npm 包
部分支持 / 不支持
🔶 以下功能存在兼容性限制：
worker_threads（部分支持）vm模块（部分支持）- 一些 Node.js 特定的边缘 API
对于生产环境，建议测试确保依赖包兼容。
从 npm/yarn/pnpm 迁移
迁移步骤
# 1. 删除现有 lockfile 和 node_modules$ rm -rf node_modules package-lock.json yarn.lock pnpm-lock.yaml
# 2. 使用 Bun 安装$ bun installBun 会读取 package.json 并生成 bun.lockb。
保持兼容性
如需与非 Bun 环境兼容，可同时生成其他格式的 lockfile：
$ bun install --yarn # 生成 yarn.lockCI/CD 适配
# GitHub Actions- uses: oven-sh/setup-bun@v2 with: bun-version: latest
- run: bun install --frozen-lockfile- run: bun run buildBun 作为运行时
Bun 不仅是包管理器，也是高性能 JavaScript 运行时。
运行 TypeScript
# 无需编译，直接运行$ bun run server.ts运行测试
# Bun 内置测试运行器$ bun test测试文件示例：
import { expect, test } from 'bun:test'
test('2 + 2', () => { expect(2 + 2).toBe(4)})构建打包
$ bun build ./src/index.ts --outdir ./dist常用命令速查
| 命令 | 用途 |
|---|---|
bun install | 安装所有依赖 |
bun add <pkg> | 添加依赖 |
bun add -d <pkg> | 添加开发依赖 |
bun add -g <pkg> | 全局安装 |
bun remove <pkg> | 移除依赖 |
bun update | 更新依赖 |
bun update -i | 交互式更新 |
bun run <script> | 运行脚本 |
bun <file> | 运行文件 |
bunx <pkg> | 执行包命令 |
bun test | 运行测试 |
bun build | 构建打包 |
bun upgrade | 升级 Bun |
bun pm cache rm | 清理缓存 |
npm vs yarn vs pnpm vs Bun
| 特性 | npm | yarn | pnpm | Bun |
|---|---|---|---|---|
| 语言 | JS | JS | JS | Zig |
| 安装速度 | 慢 | 中 | 快 | 极快 |
| 磁盘占用 | 高 | 高 | 低 | 低 |
| 运行时 | Node | Node | Node | Bun |
| TypeScript | 需编译 | 需编译 | 需编译 | 原生 |
| Windows | ✅ | ✅ | ✅ | ✅ |
| 生态成熟度 | 最高 | 高 | 高 | 中 |
常见问题
某些包不兼容
部分包依赖 Node.js 特定 API，Bun 可能不完全支持。解决方案：
- 检查 Bun 兼容性列表
- 使用替代包
- 对该项目继续使用 Node.js
lockfile 格式问题
如需与团队共享，且团队使用不同工具：
# 生成 yarn.lock 兼容文件$ bun install --yarn生产环境建议
🔶 Bun 仍在快速迭代中，对于关键生产环境：
- 确保充分测试
- 关注 Bun 的 changelog
- 考虑保留 Node.js 作为备选