bun-package-manager

Bun 包管理器

Bun 的包管理器是 npm、yarn 和 pnpm 的大幅提速替代品。速度最高可比 npm install 快 25 倍。

快速开始

# Install all dependencies
bun install

# Add packages
bun add react react-dom
bun add -D typescript @types/react

# Remove packages
bun remove lodash

# Update packages
bun update

# Run package binaries
bunx create-next-app

核心命令

命令	说明
bun install	安装所有依赖项
bun add <pkg>	添加依赖项
bun add -D <pkg>	添加开发依赖项
bun add -O <pkg>	添加可选依赖项
bun add --peer <pkg>	添加对等依赖项
bun remove <pkg>	移除依赖项
bun update [pkg]	更新依赖项
bunx <pkg>	运行包二进制文件
bun pm cache rm	清除缓存

安装标志

# Production mode (no devDependencies)
bun install --production

# Frozen lockfile (CI/CD)
bun install --frozen-lockfile
bun ci  # shorthand

# Dry run
bun install --dry-run

# Verbose/Silent
bun install --verbose
bun install --silent

# Force reinstall
bun install --force

# Global packages
bun install -g cowsay

锁文件

Bun 使用 bun.lock（自 v1.2 起采用纯文本格式）：

# Generate text lockfile
bun install --save-text-lockfile

# Upgrade from binary bun.lockb
bun install --save-text-lockfile --frozen-lockfile --lockfile-only
rm bun.lockb

工作区（单仓库）

{
  "name": "my-monorepo",
  "workspaces": ["packages/*", "apps/*"]
}

在各工作区中运行命令：

# Run in matching packages
bun run --filter 'pkg-*' build

# Run in all workspaces
bun run --filter '*' test

# Install for specific packages
bun install --filter 'pkg-a'

生命周期脚本

出于安全考虑，Bun 默认不会运行依赖项中的生命周期脚本。将可信软件包加入白名单：

{
  "trustedDependencies": ["my-trusted-package"]
}

# Skip all lifecycle scripts
bun install --ignore-scripts

# Concurrent scripts
bun install --concurrent-scripts 5

覆盖与解析

强制指定嵌套依赖项的版本：

{
  "overrides": {
    "lodash": "4.17.21"
  }
}

也支持 Yarn 风格的解析配置：

{
  "resolutions": {
    "lodash": "4.17.21"
  }
}

非 npm 依赖项

{
  "dependencies": {
    "dayjs": "git+https://github.com/iamkun/dayjs.git",
    "lodash": "git+ssh://github.com/lodash/lodash.git#4.17.21",
    "zod": "github:colinhacks/zod",
    "react": "https://registry.npmjs.org/react/-/react-18.2.0.tgz",
    "bun-types": "npm:@types/bun"
  }
}

安装策略

Bun 1.3+ 默认行为变更：从 Bun 1.3 开始，工作区默认使用 isolated（软件包无法再通过提升到根目录的 node_modules 访问未声明的依赖项）。hoisted 现在是旧版退出选项——仅当工作区软件包依赖于自身未声明的传递依赖项时才使用。

Hoisted（旧版退出选项；仍是单个非工作区软件包的默认值）

传统的扁平 node_modules：

bun install --linker hoisted

Isolated（Bun 1.3+ 工作区的默认值）

类似 pnpm 的严格隔离：

bun install --linker isolated

Isolated 可防止“幽灵依赖”——软件包只能访问已声明的依赖项。若要明确启用此策略，或在选择退出后恢复该策略，可在 bunfig.toml 中设置：

[install]
linker = "isolated"   # default for workspaces in Bun 1.3+
# linker = "hoisted"  # legacy opt-out

CI/CD

# GitHub Actions
- uses: oven-sh/setup-bun@v2
- run: bun ci  # frozen lockfile

特定平台

# Install for different platform
bun install --cpu=x64 --os=linux

安全安装

安装软件包时，请遵循供应链安全最佳实践：

• 阻止安装后脚本——Bun 默认会禁用这些脚本；可通过 package.json 中的 trustedDependencies 允许特定软件包
• 冷却期——在 bunfig.toml 中配置 minimumReleaseAge，等待 7 天后再安装新版本
• 安装前审计——运行 socket package score npm <pkg>，或使用 socket npm install <pkg>，在软件包进入项目之前进行检查

加载 dependency-upgrade 技能，了解完整的安全配置，包括 Socket CLI 集成、冷却期设置、锁文件验证和 CI 强制执行。

常见错误

错误	原因	修复方法
Cannot find module	缺少依赖项	运行 bun install
Lockfile mismatch	package.json 已更改	运行 bun install
Peer dependency	缺少对等依赖项	使用 bun add 添加对等依赖项
Lifecycle script failed	软件包不受信任	将其添加到 trustedDependencies

从其他包管理器迁移

从 pnpm 迁移

Bun 会自动迁移 pnpm-lock.yaml：

bun install  # Auto-converts to bun.lock

工作区配置会迁移到 package.json：

{
  "workspaces": {
    "packages": ["apps/*", "packages/*"],
    "catalog": {
      "react": "^18.0.0"
    }
  }
}

从 npm/Yarn 迁移

只需运行 bun install——Bun 会读取 package-lock.json 和 yarn.lock。

何时加载参考文档

遇到以下情况时，加载 references/cli-commands.md：

• 需要完整的 CLI 标志参考
• 使用高级选项

遇到以下情况时，加载 references/workspaces.md：

• 设置单仓库
• 配置工作区筛选器

遇到以下情况时，加载 references/migration.md：

• 从 npm/yarn/pnpm 迁移
• 转换锁文件