垦荒学园
  • 中文

      • Bun 包管理器

      Bun 内置了极速的包管理器，可以替代 npm、yarn、pnpm。本章介绍 Bun 包管理器的使用方法和高级特性。

      为什么使用 Bun 包管理器？

      速度对比

      安装 React 项目依赖的时间对比：
┌────────────────────────────────────────────┐
│ npm    ████████████████████████████  30s   │
│ yarn   ██████████████████████        22s   │
│ pnpm   ████████████████              16s   │
│ bun    ██                            1.5s  │
└────────────────────────────────────────────┘

      Bun 包管理器的优势：

      • 极速安装：比 npm 快 20-30 倍
      • 硬链接：节省磁盘空间
      • 兼容性：完全兼容 npm 生态
      • 零配置：无需额外设置

      基本命令

      初始化项目

      # 创建 package.json
bun init

# 交互式创建
bun init -y  # 跳过提示，使用默认值

      安装依赖

      # 安装所有依赖（根据 package.json）
bun install

# 简写
bun i

      添加依赖

      # 添加生产依赖
bun add lodash

# 添加多个依赖
bun add react react-dom

# 添加开发依赖
bun add -d typescript @types/node

# 添加可选依赖
bun add --optional fsevents

# 添加精确版本
bun add express@4.18.2

# 添加指定版本范围
bun add "express@^4.18.0"

      移除依赖

      # 移除依赖
bun remove lodash

# 移除多个依赖
bun remove react react-dom

      更新依赖

      # 更新所有依赖
bun update

# 更新特定依赖
bun update lodash

# 查看可更新的依赖
bun outdated

      package.json 管理

      依赖类型

      {
  "dependencies": {
    "express": "^4.18.0",
    "lodash": "^4.17.21"
  },
  "devDependencies": {
    "typescript": "^5.0.0",
    "@types/node": "^20.0.0"
  },
  "peerDependencies": {
    "react": "^18.0.0"
  },
  "optionalDependencies": {
    "fsevents": "^2.3.0"
  }
}

      版本规范

      写法含义
      4.18.2精确版本
      ^4.18.0兼容版本（4.x.x）
      ~4.18.0补丁版本（4.18.x）
      *任意版本
      >=4.18.0大于等于指定版本
      4.18.0 - 5.0.0版本范围

      锁文件

      bun.lockb

      Bun 使用二进制锁文件 bun.lockb：

      # 查看锁文件内容（转为 yarn.lock 格式）
bun bun.lockb

      锁文件优势

      • 更小：比 package-lock.json 小得多
      • 更快：二进制格式解析更快
      • 确定性：保证安装结果一致

      忽略锁文件

      # 忽略锁文件重新安装
bun install --no-save

      全局包管理

      安装全局包

      # 安装全局包
bun add --global typescript

# 简写
bun add -g typescript

      查看全局包

      # 全局包位置
ls ~/.bun/install/global

      移除全局包

      bun remove -g typescript

      Registry 配置

      使用镜像源

      # 临时使用镜像
bun add lodash --registry https://registry.npmmirror.com

      配置文件

      创建 bunfig.toml：

      [install]
# 使用国内镜像
registry = "https://registry.npmmirror.com"

      多 Registry 配置

      [install.scopes]
# @company 作用域使用私有 registry
"@company" = "https://npm.company.com"

# 其他包使用默认 registry

      工作空间（Monorepo）

      配置工作空间

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

      目录结构

      my-monorepo/
├── package.json
├── packages/
│   ├── shared/
│   │   └── package.json
│   └── utils/
│       └── package.json
├── apps/
│   ├── web/
│   │   └── package.json
│   └── api/
│       └── package.json
└── bun.lockb

      工作空间命令

      # 安装所有工作空间依赖
bun install

# 在特定工作空间运行命令
bun run --filter @company/web dev

# 添加依赖到特定工作空间
bun add lodash --filter @company/web

# 工作空间间添加依赖
bun add @company/shared --filter @company/web

      缓存管理

      缓存位置

      # 查看缓存目录
echo $BUN_INSTALL/install/cache

      清理缓存

      # 清理包缓存
bun pm cache rm

# 清理所有缓存
rm -rf ~/.bun/install/cache

      离线安装

      # 优先使用缓存
bun install --prefer-offline

# 完全离线安装
bun install --offline

      高级安装选项

      安装选项

      # 只安装生产依赖
bun install --production

# 冻结锁文件（CI 环境推荐）
bun install --frozen-lockfile

# 不执行生命周期脚本
bun install --ignore-scripts

# 强制重新安装
bun install --force

      查看依赖树

      # 查看依赖树
bun pm ls

# 查看特定包的依赖
bun pm ls lodash

# 查看为什么安装某个包
bun pm why lodash

      发布包

      准备发布

      {
  "name": "@username/my-package",
  "version": "1.0.0",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "files": [
    "dist"
  ],
  "scripts": {
    "build": "bun build src/index.ts --outdir dist",
    "prepublishOnly": "bun run build"
  }
}

      发布到 npm

      # 登录 npm
npm login

# 发布包
npm publish

# 发布带 scope 的包
npm publish --access public

      与其他包管理器对比

      命令对照

      操作npmyarnpnpmbun
      安装依赖npm installyarnpnpm installbun install
      添加依赖npm install pkgyarn add pkgpnpm add pkgbun add pkg
      添加开发依赖npm install -D pkgyarn add -D pkgpnpm add -D pkgbun add -d pkg
      移除依赖npm uninstall pkgyarn remove pkgpnpm remove pkgbun remove pkg
      运行脚本npm run cmdyarn cmdpnpm cmdbun run cmd
      全局安装npm install -g pkgyarn global add pkgpnpm add -g pkgbun add -g pkg

      迁移到 Bun

      从其他包管理器迁移非常简单：

      # 删除旧的锁文件和 node_modules
rm -rf node_modules package-lock.json yarn.lock pnpm-lock.yaml

# 使用 Bun 重新安装
bun install

      常见问题

      安装失败

      # 清理后重试
rm -rf node_modules bun.lockb
bun install

# 使用详细模式查看错误
bun install --verbose

      版本冲突

      # 查看冲突原因
bun pm why conflicting-package

# 强制使用特定版本
bun add package@version --force

      私有包认证

      # bunfig.toml
[install.scopes]
"@private" = { url = "https://npm.private.com", token = "$NPM_TOKEN" }

      小结

      本章介绍了：

      • ✅ Bun 包管理器的基本命令
      • ✅ 依赖管理和版本控制
      • ✅ Registry 和镜像配置
      • ✅ 工作空间（Monorepo）支持
      • ✅ 缓存管理和离线安装
      • ✅ 从其他包管理器迁移

      下一步

      继续阅读 模块系统 了解 Bun 对 ES 模块和 CommonJS 的支持。