bun install

bun CLI 包含一个与 Node.js 兼容的包管理器，它旨在成为 npm、yarn 和 pnpm 的一个显著更快的替代品。它是一个独立的工具，可以在现有的 Node.js 项目中使用；如果你的项目有 package.json，bun install 可以帮助你加快工作流程。

⚡️ 快 25 倍 — 在任何 Node.js 项目中，将 npm install 切换为 bun install，即可将安装速度提高高达 25 倍。

# If this returns a version >= 5.6, you don't need to do anything

uname -r

# Install the official Ubuntu hardware enablement kernel

sudo apt install --install-recommends linux-generic-hwe-20.04

安装项目的全部依赖项

bun install

运行 bun install 将会：

• 安装所有 dependencies、devDependencies 和 optionalDependencies。Bun 默认安装 peerDependencies。
• 在适当的时间运行项目的 {pre|post}install 和 {pre|post}prepare 脚本。出于安全原因，Bun *不会执行*已安装依赖项的生命周期脚本。
• 在项目根目录写入一个 bun.lock 锁定文件。

Logging

修改日志的详细程度

bun install --verbose # debug logging

bun install --silent  # no logging

生命周期脚本

与其他 npm 客户端不同，Bun 不会执行已安装依赖项的任意生命周期脚本，如 postinstall。执行任意脚本存在潜在的安全风险。

要告诉 Bun 允许特定包的生命周期脚本，请将该包添加到 package.json 中的 trustedDependencies 字段。

{
  "name": "my-app",
  "version": "1.0.0",
  "trustedDependencies": ["my-trusted-package"]
}

然后重新安装该包。Bun 将读取此字段并为 my-trusted-package 运行生命周期脚本。

生命周期脚本将在安装过程中并行运行。要调整并发脚本的最大数量，请使用 --concurrent-scripts 标志。默认值为报告的 CPU 数量或 GOMAXPROCS 的两倍。

bun install --concurrent-scripts 5

Workspaces

Bun 支持 package.json 中的 "workspaces"。有关完整文档，请参阅 Package manager > Workspaces。

{
  "name": "my-app",
  "version": "1.0.0",
  "workspaces": ["packages/*"],
  "dependencies": {
    "preact": "^10.5.13"
  }
}

为特定包安装依赖项

在 monorepo 中，你可以使用 --filter 标志来安装一组包的依赖项。

# Install dependencies for all workspaces except `pkg-c`

bun install --filter '!pkg-c'

# Install dependencies for only `pkg-a` in `./packages/pkg-a`

bun install --filter './packages/pkg-a'

有关使用 bun install 进行过滤的更多信息，请参阅 Package Manager > Filtering。

Overrides and resolutions

Bun 支持 package.json 中的 npm "overrides" 和 Yarn 的 "resolutions"。这些是指定元依赖项（依赖项的依赖项）版本范围的机制。有关完整文档，请参阅 Package manager > Overrides and resolutions。

{
  "name": "my-app",
  "dependencies": {
    "foo": "^2.0.0"
  },
  "overrides": {
    "bar": "~4.4.0"
  }
}

全局包

要全局安装包，请使用 -g/--global 标志。通常用于安装命令行工具。

bun install --global cowsay # or `bun install -g cowsay`

cowsay "Bun!"

 ______
< Bun! >
 ------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

生产模式

以生产模式安装（即不安装 devDependencies 或 optionalDependencies）

bun install --production

为了实现可重现的安装，请使用 --frozen-lockfile。这将安装锁定文件中指定的每个包的精确版本。如果你的 package.json 与 bun.lock 不符，Bun 将会报错退出。锁定文件不会被更新。

bun install --frozen-lockfile

有关 Bun 的锁定文件 bun.lock 的更多信息，请参阅 Package manager > Lockfile。

忽略依赖项

要省略 dev、peer 或 optional 依赖项，请使用 --omit 标志。

# Exclude "devDependencies" from the installation. This will apply to the
# root package and workspaces if they exist. Transitive dependencies will
# not have "devDependencies".

bun install --omit dev

# Install only dependencies from "dependencies"

bun install --omit=dev --omit=peer --omit=optional

Dry run

执行 dry run（即不实际安装任何内容）

bun install --dry-run

非 npm 依赖项

Bun 支持从 Git、GitHub 以及本地或远程托管的 tarball 安装依赖项。有关完整文档，请参阅 Package manager > Git, GitHub, and tarball dependencies。

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

安装策略

Bun 支持两种包安装策略，它们决定了依赖项如何在 node_modules 中组织。

Hoisted installs（单个项目的默认值）

传统的 npm/Yarn 方法，将依赖项扁平化到共享的 node_modules 目录中。

bun install --linker hoisted

Isolated installs

一种类似于 pnpm 的方法，它创建严格的依赖项隔离，以防止幻影依赖项。

bun install --linker isolated

Isolated installs 在 node_modules/.bun/ 中创建一个中心包存储，并在顶层 node_modules 中创建符号链接。这确保了包只能访问其声明的依赖项。

有关 isolated installs 的完整文档，请参阅 Package manager > Isolated installs。

磁盘效率

Bun 使用位于 ~/.bun/install/cache/ 的全局缓存来最大限度地减少磁盘使用。包只存储一次，并使用硬链接（Linux/Windows）或写时复制（macOS）链接到 node_modules，因此项目之间重复的包不会占用额外的磁盘空间。

有关完整文档，请参阅 Package manager > Global cache。

最小发布年龄

为了防止恶意包快速发布的供应链攻击，你可以配置 npm 包的最小年龄要求。在安装过程中，发布时间晚于指定阈值（以秒为单位）的包版本将被过滤掉。

# Only install package versions published at least 3 days ago

bun add @types/bun --minimum-release-age 259200 # seconds

你也可以在 bunfig.toml 中进行配置。

[install]
# Only install package versions published at least 3 days ago
minimumReleaseAge = 259200 # seconds

# Exclude trusted packages from the age gate
minimumReleaseAgeExcludes = ["@types/node", "typescript"]

当最小年龄过滤器激活时

• 仅影响新的包解析 - bun.lock 中现有的包保持不变。
• 在解析时，所有依赖项（直接和传递的）都会被过滤以满足年龄要求。
• 当版本因年龄限制而被阻止时，稳定性检查会检测到快速的 bug 修复模式。
  • 如果多个版本在年龄限制附近发布，它会扩展过滤器以跳过这些可能不稳定的版本，并选择一个更旧、更成熟的版本。
  • 搜索年龄限制后最多 7 天，但如果仍发现快速发布，则忽略稳定性检查。
  • 精确版本请求（例如 package@1.1.1）仍然遵循年龄限制，但会绕过稳定性检查。
• 没有 time 字段的版本被视为通过年龄检查（npm 注册表应始终提供时间戳）。

有关更高级的安全扫描，包括与服务和自定义过滤的集成，请参阅 Package manager > Security Scanner API。

Configuration

bun install 的默认行为可以在 bunfig.toml 中进行配置。默认值如下所示。

[install]

# whether to install optionalDependencies
optional = true

# whether to install devDependencies
dev = true

# whether to install peerDependencies
peer = true

# equivalent to `--production` flag
production = false

# equivalent to `--save-text-lockfile` flag
saveTextLockfile = false

# equivalent to `--frozen-lockfile` flag
frozenLockfile = false

# equivalent to `--dry-run` flag
dryRun = false

# equivalent to `--concurrent-scripts` flag
concurrentScripts = 16 # (cpu count or GOMAXPROCS) x2

# installation strategy: "hoisted" or "isolated"
# default: "hoisted"
linker = "hoisted"

# minimum age config
minimumReleaseAge = 259200 # seconds
minimumReleaseAgeExcludes = ["@types/node", "typescript"]

CI/CD

使用官方的 oven-sh/setup-bun action 在 GitHub Actions 管道中安装 bun。

name: bun-types
jobs:
  build:
    name: build-app
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
      - name: Install bun
        uses: oven-sh/setup-bun@v2
      - name: Install dependencies
        run: bun install
      - name: Build app
        run: bun run build

对于希望强制执行可重现构建的 CI/CD 环境，请使用 bun ci，如果 package.json 与锁定文件不同步，则会使构建失败。

bun ci

这等同于 bun install --frozen-lockfile。它从 bun.lock 安装精确的版本，如果 package.json 与锁定文件不匹配则会失败。要使用 bun ci 或 bun install --frozen-lockfile，你必须将 bun.lock 提交到版本控制。

并且，不要运行 bun install，而是运行 bun ci。

name: bun-types
jobs:
  build:
    name: build-app
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
      - name: Install bun
        uses: oven-sh/setup-bun@v2
      - name: Install dependencies
        run: bun ci
      - name: Build app
        run: bun run build