bun add

添加特定包：

terminal

bun add preact

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

terminal

bun add [email protected]
bun add zod@^3.0.0
bun add zod@latest

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

`--dev`

别名 — --development，-d，-D

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

terminal

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

`--optional`

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

terminal

bun add --optional lodash

`--peer`

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

terminal

bun add --peer @types/bun

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

`--exact`

别名 — -E

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

terminal

bun add react --exact
bun add react -E

package.json 中的区别：

package.json

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

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

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

terminal

bun add --help

`--catalog`

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

terminal

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

package.json

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

packages/app/package.json

{
  "dependencies": {
    "react": "catalog:"
  }
}

如果目录中已有条目，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`

别名 — -F

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

terminal

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`

别名 — bun add --global、bun add -g、bun install --global 和 bun install -g

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

terminal

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

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

配置全局安装行为

bunfig.toml

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

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

受信任的依赖

与其他 npm 客户端不同，Bun 不会执行已安装依赖的任意生命周期脚本，如 postinstall。这些脚本存在安全风险，可能在您的机器上执行任意代码。要让 Bun 允许特定包的生命周期脚本，请在您的 package.json 中将该包添加到 trustedDependencies。

package.json

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

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

Git 依赖

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

terminal

bun add [email protected]:moment/moment.git

安装私有仓库时，系统需具备相应的 SSH 凭据以访问该仓库。

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

package.json

{
  "dependencies": {
    "dayjs": "git+https://github.com/iamkun/dayjs.git",
    "lodash": "git+ssh://github.com/lodash/lodash.git#4.17.21",
    "moment": "[email protected]:moment/moment.git",
    "zod": "github:colinhacks/zod"
  }
}

Tarball 依赖

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

terminal

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

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

package.json

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

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

CLI 使用方法

bun add <package> <@version>

依赖管理

boolean

不安装 devDependencies。别名：-p

string

安装时排除 dev、optional 或 peer 依赖

boolean

全局安装。别名：-g

boolean

添加依赖到 devDependencies。别名：-d

boolean

添加依赖到 optionalDependencies

boolean

添加依赖到 peerDependencies

boolean

添加精确版本，而非 ^ 范围。别名：-E

boolean

仅在 package.json 中不存在该依赖时才添加

string

将解析后的版本添加到根目录 package.json 的 catalog 中，并以 catalog: 的形式依赖它； —catalog=NAME 指向 catalogs.NAME

string

将软件包添加到匹配的工作区，而不是当前软件包。别名：-F

项目文件与锁文件

boolean

生成 yarn.lock 文件（yarn v1）。别名：-y

boolean

不更新 package.json 或保存锁文件

boolean

default:"true"

保存到 package.json

boolean

不允许修改锁文件

boolean

将依赖添加到项目 package.json 的 trustedDependencies 并安装该包

boolean

保存为文本格式的锁文件

boolean

仅生成锁文件，不安装依赖

安装控制

boolean

解析软件包，但不安装它们、不更新 package.json，也不保存锁文件（项目自身的生命周期脚本仍会运行）

boolean

总是从注册表请求最新版本并重新安装所有依赖。别名：-f

boolean

跳过新下载包的完整性校验

boolean

跳过所有软件包的生命周期脚本，包括项目的 package.json 和可信依赖中的脚本

boolean

递归分析并安装作为参数传入文件的依赖（使用 Bun 的打包器）。别名：-a

网络与注册表

string

提供证书颁发机构签名证书

string

与 —ca 相同，但通过证书文件路径提供

string

默认使用指定注册表，覆盖 .npmrc、bunfig.toml 和环境变量

number

default:"48"

最大并发网络请求数

性能与资源

string

用于安装依赖的平台专属优化。可能的值：clonefile（macOS 上的默认值）、hardlink（Linux 和 Windows 上的默认值）、symlink、copyfile

number

生命周期脚本的最大并发任务数（默认值：CPU 核心数的 2 倍）

缓存

string

从指定目录路径存储和加载缓存数据

boolean

完全忽略清单缓存

输出与日志

boolean

不输出任何日志

boolean

输出超详细日志

boolean

关闭进度条

boolean

不打印总结信息

全局配置与上下文

string

指定配置文件路径（bunfig.toml）。别名：-c

string

设置当前工作目录

帮助

boolean

显示此帮助菜单。别名：-h

核心命令

发布与分析

工作区管理

高级配置

`--dev`

`--optional`

`--peer`

`--exact`

`--catalog`

`--filter`

`--global`

受信任的依赖

Git 依赖

Tarball 依赖

CLI 使用方法

依赖管理

项目文件与锁文件

安装控制

网络与注册表

性能与资源

缓存

输出与日志

全局配置与上下文

帮助

​--dev

​--optional

​--peer

​--exact

​--catalog

​--filter

​--global

​受信任的依赖

​Git 依赖

​Tarball 依赖

​CLI 使用方法

​依赖管理

​项目文件与锁文件

​安装控制

​网络与注册表

​性能与资源

​缓存

​输出与日志

​全局配置与上下文

​帮助

`--dev`

`--optional`

`--peer`

`--exact`

`--catalog`

`--filter`

`--global`

受信任的依赖

Git 依赖

Tarball 依赖

CLI 使用方法

依赖管理

项目文件与锁文件

安装控制

网络与注册表

性能与资源

缓存

输出与日志

全局配置与上下文

帮助