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>

相依管理

專案檔案與鎖檔案

安裝控制

網路與登錄檔

效能與資源

快取

輸出與日誌

全域性設定與上下文

幫助