bun add

添加特定包：

bun add preact

指定版本、版本范围或标签：

bun add zod@3.20.0
bun add zod@^3.0.0
bun add zod@latest

除非传入 --dev、--optional 或 --peer，否则 Bun 会将包写入 dependencies。如果 package.json 已在其他分组中列出了该包，Bun 会在原位置更新该条目。

--dev

将包作为开发依赖（"devDependencies"）添加：

bun add --dev @types/react
bun add -d @types/react

--optional

将包作为可选依赖（"optionalDependencies"）添加：

bun add --optional lodash

--peer

将包作为对等依赖（"peerDependencies"）添加：

bun add --peer @types/bun

Bun 默认会安装对等依赖，因此不需要额外的 devDependencies 条目。

--exact

要将软件包固定为已解析的版本，请使用 --exact。Bun 会将确切的版本号写入 package.json，而不是版本范围。

bun add react --exact
bun add react -E

package.json 中的区别：

{
  "dependencies": {
    // 不使用 --exact
    "react": "^18.2.0", // 匹配 >= 18.2.0 < 19.0.0

    // 使用 --exact
    "react": "18.2.0" // 仅精确匹配 18.2.0 版本
  }
}

查看此命令的完整选项列表：

bun add --help

--catalog

在工作区中，--catalog 会将版本写入根目录的 package.json catalog，并将 "catalog:" 添加到当前包。--catalog=<name> 使用命名目录（workspaces.catalogs.<name>），并写入 "catalog:<name>"。

bun add react --catalog
bun add vitest --catalog=testing

// root package.json
{
  "workspaces": {
    "packages": ["packages/*"],
    "catalog": {
      "react": "^18.2.0" // [!code ++]
    }
  }
}

{
  "dependencies": {
    "react": "catalog:" // [!code ++]
  }
}

• 如果目录中已有条目，Bun 会复用该条目，并仅将 "catalog:" 写入当前包。传入显式版本（bun add react@19 --catalog）可替换该条目——这会影响所有引用它的包。
• 如果省略版本，且当前 package.json 已有版本范围（"react": "^18.2.0"），Bun 会将该版本范围添加到目录中。
• 已引用 "catalog:<name>" 的包会继续使用该目录。
• 使用 = 附加名称：--catalog=testing，而不是 --catalog testing。
• Bun 会在目录中以包的实际名称记录 tarball 和 Git 说明符。它会拒绝相对路径和工作区包。

即使没有该标志，如果默认目录中已经列出了 react，bun add react（不带版本）也会写入 "catalog:"。传入版本则会写入具体范围。

--filter

在 monorepo 中，将包添加到匹配的工作区，而不是当前目录的包中。有关模式语法，请参阅筛选。重复该标志可组合多个模式；!pattern 用于排除。

bun add zod --filter api
bun add -d typescript --filter './packages/*'
bun add ./vendor/logger --filter '*'
bun remove zod --filter '*' --filter '!api'

• * 匹配每个工作区包，但不包括根目录。要包含根目录，请指定其名称：--filter '*' --filter '<root-name>'。
• 如果没有工作区匹配，Bun 不会写入任何内容，并且命令会失败。
• Bun 会从当前目录解析本地路径，并将它们重写为相对于每个选定包的路径。
• 与 bun install --filter 一样，Bun 会更新整个仓库的 bun.lock，但只会将选定的工作区链接到 node_modules。
• 不能与 --global 同时使用。

--global

要全局安装软件包，请使用 -g/--global 标志。这不会修改当前项目的 package.json。使用它来安装命令行工具。

bun add --global cowsay # 或 `bun add -g cowsay`
cowsay "Bun!"

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

[install]
# `bun add --global` 安装包的位置
globalDir = "~/.bun/install/global"

# 全局安装的包二进制文件链接位置
globalBinDir = "~/.bun/bin"

受信任的依赖

与其他 npm 客户端不同，Bun 不会执行已安装依赖的任意生命周期脚本，如 postinstall。这些脚本存在安全风险，可能在您的机器上执行任意代码。

要让 Bun 允许特定包的生命周期脚本，请在您的 package.json 中将该包添加到 trustedDependencies。

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

Bun 会读取此字段，并运行 my-trusted-package 的生命周期脚本。

Git 依赖

添加来自公共或私有 Git 仓库的依赖：

bun add git@github.com:moment/moment.git

Bun 支持多种协议，包括 github、git、git+ssh 和 git+https。

{
  "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"
  }
}

Tarball 依赖

包名可以对应一个公开托管的 .tgz 文件。Bun 会从该 tarball URL 下载并安装包，而不是从包注册表安装。

bun add zod@https://registry.npmjs.org/zod/-/zod-3.21.4.tgz

bun add 会将 URL 写入你的 package.json：

{
  "dependencies": {
    "zod": "https://registry.npmjs.org/zod/-/zod-3.21.4.tgz"
  }
}

Tarball URL 可以包含凭据，例如 https://user:password@example.com/zod-3.21.4.tgz。Bun 会像 npm 一样，将这些凭据作为 Authorization: Basic 标头发送，并在请求 URL 时移除凭据。包含凭据的 URL 会写入 package.json 和锁文件。

CLI 使用方法

bun add <package> <@version>

依赖管理

项目文件与锁文件

安装控制

网络与注册表

性能与资源

缓存

输出与日志

全局配置与上下文

帮助