bun install

基本用法

bun install react
bun install react@19.1.1 # 指定版本
bun install react@latest # 指定標籤

bun CLI 包含一個相容 Node.js 的套件管理器，旨在以顯著更快的速度替代 npm、yarn 和 pnpm。它是一個獨立工具，可在現有的 Node.js 專案中執行；如果你的專案中有 package.json，就可以使用 bun install。

# 如果傳回版本號 >= 5.6，則無需操作
uname -r

# 安裝 Ubuntu 官方硬體支援核心
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 鎖檔案到專案根目錄。

日誌記錄

調整日誌詳情級別：

bun install --verbose # 除錯日誌
bun install --silent  # 靜默無日誌

生命週期指令碼

與其他 npm 客戶端不同，Bun 不會執行安裝相依的任意生命週期指令碼（如 postinstall）。執行任意指令碼存在潛在安全風險。

若需允許 Bun 針對特定包執行生命週期指令碼，請在你的 package.json 中將該包新增到 trustedDependencies 欄位。

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

然後重新安裝該包。Bun 會讀取此欄位並執行 my-trusted-package 的生命週期指令碼。

生命週期指令碼會在安裝期間並行執行。若要調整並行指令碼的最大數量，請使用 --concurrent-scripts 標誌。預設值為報告的 CPU 數量的兩倍或 GOMAXPROCS。

bun install --concurrent-scripts 5

Bun 會自動最佳化熱門包（如 esbuild 和 sharp）的 postinstall 指令碼，確定哪些指令碼需要執行。要停用這些最佳化：

BUN_FEATURE_FLAG_DISABLE_NATIVE_DEPENDENCY_LINKER=1 bun install
BUN_FEATURE_FLAG_DISABLE_IGNORE_SCRIPTS=1 bun install

工作區（Workspaces）

Bun 支援 package.json 中的 "workspaces"。請參閱工作區。

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

為特定包安裝相依

在 monorepo 中，可以通過 --filter 引數針對部分包安裝相依。

# 為除了 `pkg-c` 之外的所有工作區安裝相依
bun install --filter '!pkg-c'

# 僅為 `./packages/pkg-a` 中的 `pkg-a` 安裝相依
bun install --filter './packages/pkg-a'

請參閱篩選。

覆蓋與解析

Bun 支援 package.json 中 npm 的 "overrides" 和 Yarn 的 "resolutions"。兩者都為_元相依_（即你的相依項的相依項）指定版本範圍。請參閱覆蓋與解析。

{
  "name": "my-app",
  "dependencies": {
    "foo": "^2.0.0"
  },
  "overrides": { // [!code ++]
    "bar": "~4.4.0" // [!code ++]
  } // [!code ++]
}

全域性安裝包

要全域性安裝包，請使用 -g/--global 標誌。使用它來安裝命令列工具。

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

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

生產模式

要以生產模式安裝（不包含 devDependencies）：

bun install --production

--production 等同於 --frozen-lockfile。它只控制要安裝的內容。先前安裝時已經在 node_modules 中的 devDependencies 會繼續保留。使用 bun prune --production 將它們移除。

如需可復現安裝，請使用 --frozen-lockfile。Bun 會安裝鎖檔案中指定的確切版本，並且不會更新鎖檔案。如果你的 package.json 與 bun.lock 不一致，Bun 會以錯誤退出。

bun install --frozen-lockfile

Bun 不會在 CI 中自動啟用 --frozen-lockfile；請傳入該標誌或使用 bun ci。如果完全不存在鎖檔案，--frozen-lockfile 會從 package.json 安裝，但不會寫入鎖檔案。

--frozen-lockfile 可用於經過精簡的 monorepo 檢出目錄（例如 turbo prune 的輸出，或只複製了部分工作區資料夾的 Docker 上下文）。如果 bun.lock 中列出的工作區在磁碟上缺少 package.json，Bun 會跳過它，並顯示 note:，且不會安裝其專屬相依。如果剩餘的工作區相依於被跳過的工作區，安裝將失敗。

如需在不安裝的情況下驗證鎖檔案，請使用 bun install --frozen-lockfile --dry-run。

離線安裝

使用已預熱的快取時，bun install 可以在沒有網路的情況下執行：

# 無論快取資料的時間有多舊，都使用快取的軟體包後設資料；僅獲取快取中缺少的內容
bun install --prefer-offline

# 完全不訪問網路（登錄檔、tarball URL、git）；未快取的必需相依會導致錯誤
bun install --offline

--prefer-offline 也是 bunfig.toml 中 install.prefer = "offline" 所選擇的選項；install.offline = true 是 --offline 的設定形式。使用完整的還原快取時，--offline --frozen-lockfile 可讓 CI 安裝完全確定且無需網路；而 --prefer-offline 仍會獲取快取中缺少的內容。

安裝只能確保快取放入 node_modules 中的軟體包。要為 --offline 安裝預熱快取，請在同一平臺上執行安裝，並至少放入相同的軟體包。使用 --production 或 --omit 的安裝不會快取被省略的分組。

有關 bun.lock 的更多資訊，請參閱鎖檔案。

省略相依

若要省略開發、對等或可選相依，請使用 --omit 標誌。

# 從安裝中排除 "devDependencies"。同時適用於根包和工作區（若存在）。傳遞相依不會擁有 devDependencies。
bun install --omit dev

# 僅安裝 "dependencies"
bun install --omit=dev --omit=peer --omit=optional

演練模式

要執行演練而不安裝任何內容：

bun install --dry-run

非 npm 相依

Bun 支援從 Git、GitHub 以及本地或遠端託管的 tarball 安裝相依。請參閱 bun add。

{
  "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 的方式，可建立嚴格的相依隔離，以防止幻影相依：即無需在 package.json 中宣告就可以匯入的包：

bun install --linker isolated

隔離安裝會在 node_modules/.bun/ 建立中央包儲存，並在頂層 node_modules 中使用符號連結，確保包只能訪問宣告的相依。

預設策略

預設連結器策略依據是否是新專案或已有專案：

• 新工作區/monorepo：isolated（防止幻影相依）
• 新單包專案：hoisted（傳統 npm 行為）
• 舊專案（v1.3.2 之前建立）：hoisted（保留向後相容）

鎖檔案中的 configVersion 欄位會控制預設值。詳細說明請參閱隔離安裝。

最小發布年齡

為防範惡意軟體包被快速釋出所導致的供應鏈攻擊，你可以為 npm 軟體包設定最低釋出時間要求。Bun 會在安裝過程中篩除釋出時間距今少於指定閾值（以秒為單位）的軟體包版本。

# 只安裝至少三天前釋出的版本
bun add @types/bun --minimum-release-age 259200 # 秒

也可以在 bunfig.toml 設定：

[install]
# 最低釋出時間為三天
minimumReleaseAge = 259200 # 秒

# 排除信任包繞過年齡檢測
minimumReleaseAgeExcludes = ["@types/node", "typescript"]

啟用最小年齡過濾時：

• 它隻影響新的軟體包解析；bun.lock 中已有的軟體包保持不變
• Bun 會在解析相依時過濾所有相依（直接相依和傳遞相依），以滿足年齡要求
• 當年齡門檻阻止某些版本時，穩定性檢查會檢測快速修復缺陷的釋出模式
  • 如果多個版本在剛剛超出年齡門檻時接連發布，Bun 會擴大過濾範圍，跳過這些可能不穩定的版本，並選擇更舊、更成熟的版本
  • 檢查會在年齡門檻之後最多搜尋 7 天；如果這段時間內仍有頻繁釋出，Bun 會忽略穩定性檢查
  • 精確版本請求（如 package@1.1.1）仍會遵守年齡門檻，但會繞過穩定性檢查
• Bun 會將沒有 time 欄位的版本視為通過年齡檢查（npm 登錄檔應始終提供時間戳）

如需更高階的安全掃描，包括與服務整合和自定義過濾，請參閱安全掃描器 API。

設定

通過 bunfig.toml 設定 bun install

在執行 bun install、bun remove 和 bun add 時，Bun 會在以下位置查詢 bunfig.toml：

1. $XDG_CONFIG_HOME/.bunfig.toml 或 $HOME/.bunfig.toml
2. 當前目錄下的 ./bunfig.toml

如果 Bun 找到這兩個檔案，就會同時載入。專案的 bunfig.toml 中設定的鍵會覆蓋全域性檔案中的同名鍵。

通過 bunfig.toml 進行設定是可選的。以下是預設值：

[install]

# 是否安裝 optionalDependencies
optional = true

# 是否安裝 devDependencies
dev = true

# 是否安裝 peerDependencies
peer = true

# 等同於 `--production`
production = false

# 等同於 `--save-text-lockfile` 標誌
saveTextLockfile = true

# 等同於 `--frozen-lockfile`
frozenLockfile = false

# 等同於 `--dry-run`
dryRun = false

# 等同於 `--concurrent-scripts`
concurrentScripts = 16 # CPU 核心數或 GOMAXPROCS 的 2 倍

# 安裝策略："hoisted" 或 "isolated"
# 預設相依於鎖檔案 configVersion 和是否使用工作區：
# - configVersion = 1：若使用工作區則為 "isolated"，否則為 "hoisted"
# - configVersion = 0："hoisted"
linker = "hoisted"

# 最小發布時間設定
minimumReleaseAge = 259200 # 秒
minimumReleaseAgeExcludes = ["@types/node", "typescript"]

通過環境變數設定

環境變數的優先順序高於 bunfig.toml。

Bun 會在目標平臺上使用可用的最快安裝方式：在 macOS 上使用 clonefile，在 Linux 和 Windows 上使用 hardlink。你可以通過 --backend 標誌更改安裝方式。如果 clonefile 和 hardlink 不可用或出錯，則會回退到平臺特定的檔案複製實現。

Bun 會將從 npm 安裝的軟體包儲存在 ~/.bun/install/cache/${name}@${version} 中。如果 semver 版本包含 build 或 pre 標籤，Bun 會將其替換為該值的雜湊。這可以降低因檔案路徑過長而導致錯誤的可能性，但會使確定軟體包在磁碟上的安裝位置變得更加複雜。

當 node_modules 資料夾存在時，Bun 會通過檢查預期 node_modules 位置中的 package.json 裡的 "name" 和 "version" 是否與預期的軟體包名稱和版本匹配，來決定是否安裝軟體包。Bun 使用自定義 JSON 解析器，在找到 "name" 和 "version" 後就會停止解析。

當不存在 bun.lock，或者 package.json 中的軟體包相依發生變化時，Bun 會在解析過程中立即下載並提取 tarball。

當存在 bun.lock 且 package.json 未發生變化時，Bun 會延遲下載缺失的相依。如果 node_modules 中的預期位置已存在名稱和版本匹配的軟體包，Bun 就不會嘗試下載 tarball。

CI/CD

在 GitHub Actions 中使用官方 oven-sh/setup-bun 動作安裝 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 ci 等同於 bun install --frozen-lockfile。它會從 bun.lock 安裝確切版本；如果 package.json 與鎖檔案不匹配，則會失敗。若要使用 bun ci 或 bun install --frozen-lockfile，必須將 bun.lock 提交到版本控制系統。

在工作流中執行 bun ci，而不是 bun install：

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

平臺特定相依？

Bun 會將 npm 中規範化的 cpu 和 os 值連同已解析的軟體包儲存在鎖檔案中。執行環境會跳過為當前目標平臺停用的軟體包的下載、提取和安裝。這意味著即使最終安裝的軟體包有所變化，不同平臺/架構上的鎖檔案也不會改變。

--cpu 和 --os 引數

你可以覆蓋目標平臺進行包選擇：

bun install --cpu=x64 --os=linux

這些標誌會為指定的平臺安裝包，而不是當前系統。你可以在跨平臺建置，或為不同環境準備部署內容時使用它們。

--cpu 的可接受值：arm、arm64、ia32、mips、mipsel、ppc、ppc64、s390、s390x、x32、x64

--os 的可接受值：aix、darwin、freebsd、linux、openbsd、sunos、win32、android

對等相依？

Bun 像 Yarn 一樣處理對等相依：bun install 會自動安裝它們。如果該相依在 peerDependenciesMeta 中被標記為可選，Bun 會盡可能使用現有的相依。

鎖檔案

bun.lock 是 Bun 的鎖檔案格式。請參閱我們關於文本鎖檔案的部落格文章。

在 Bun 1.2 之前，鎖檔案採用二進位制格式，名為 bun.lockb。要將舊鎖檔案升級為新格式，請執行 bun install --save-text-lockfile --frozen-lockfile --lockfile-only，然後刪除 bun.lockb。

快取

刪除快取：

bun pm cache rm
# 或
rm -rf ~/.bun/install/cache

平臺特定後端

為了提升效能，bun install 會根據平臺使用不同的系統呼叫來安裝相依。你可以使用 --backend 標誌強制指定後端。

hardlink 是 Linux 和 Windows 上的預設後端。基準測試表明，它在 Linux 上速度最快。

rm -rf node_modules
bun install --backend hardlink

clonefile 是 macOS 預設後端，效能最好，僅 macOS 可用。

rm -rf node_modules
bun install --backend clonefile

clonefile_each_dir 與 clonefile 類似，但會按目錄逐個克隆檔案。它僅在 macOS 上可用，執行速度通常比 clonefile 慢。與 clonefile 不同，clonefile_each_dir 不會通過一次系統呼叫遞迴克隆子目錄。

rm -rf node_modules
bun install --backend clonefile_each_dir

copyfile 是上述後端失敗時使用的回退方案，速度最慢。在 macOS 上，它使用 fcopyfile()；在 Linux 上，它使用 copy_file_range()。

rm -rf node_modules
bun install --backend copyfile

symlink 通常僅在內部用於 file: 相依（例如 file:../foo 和傳遞的 file: 相依）。link: 相依不會使用此後端；Bun 會將它們安裝為指向連結目錄的單個符號連結。

若用 --backend=symlink 安裝，除非每個相依都有自己的 node_modules，否則 Node.js 不會正確解析相依的 node_modules，除非對 node 或 bun 使用 --preserve-symlinks 引數。詳見 Node.js 關於 --preserve-symlinks 文件。

rm -rf node_modules
bun install --backend symlink
bun --preserve-symlinks ./my-file.js
node --preserve-symlinks ./my-file.js # https://nodejs.org/api/cli.html#--preserve-symlinks

npm 登錄檔後設資料

Bun 使用二進位制格式快取 npm 登錄檔響應。與 JSON 相比，這種格式的載入速度快得多，且磁碟佔用通常更小。這些檔案位於 ~/.bun/install/cache/*.npm。檔名格式為 ${hash(packageName)}.npm。檔名使用雜湊，這樣 Bun 就不需要為作用域包建立額外目錄。

Bun 使用 Cache-Control 時會忽略 Age。這可以提升效能，但意味著 Bun 獲取的 npm 最新軟體包版本後設資料可能會滯後約 5 分鐘。

pnpm 遷移

Bun 會自動遷移 pnpm 專案。當 Bun 檢測到 pnpm-lock.yaml 檔案且不存在 bun.lock 檔案時，會在安裝過程中將鎖檔案轉換為 bun.lock。原始的 pnpm-lock.yaml 檔案保持不變。

bun install

僅當不存在 bun.lock 時才會執行遷移。目前沒有用於停用 pnpm 遷移的選項。

遷移內容：

鎖檔案遷移

• 將 pnpm-lock.yaml（鎖檔案版本 7–9，包括 pnpm 11 的多文件檔案）轉換為 bun.lock
• 保留已解析的版本和完整性雜湊
• 保留對等相依範圍和 peerDependenciesMeta，因此下一次 bun install 不會更改遷移後的鎖檔案
• 遷移 git、GitHub、tarball URL、file: 和 npm: 別名相依，包括傳遞相依
• 通過 pnpm-workspace.yaml 中的 namedRegistries 解析 pnpm 命名登錄檔（name@registry:version）
• 將注入的工作區包（dependenciesMeta.*.injected）轉換為普通工作區相依
• 處理已修補的相依，將 pnpm 僅包含雜湊的 patchedDependencies 條目與補丁檔案進行匹配
• 跳過 runtime: 條目（由 pnpm 管理的 Node.js 版本），並顯示警告

工作區設定

檢測到 pnpm-workspace.yaml 時，將工作區設定遷移至根 package.json：

packages:
  - "apps/*"
  - "packages/*"

catalog:
  react: ^18.0.0
  typescript: ^5.0.0

catalogs:
  build:
    webpack: ^5.0.0
    babel: ^7.0.0

Bun 會將工作區包列表和 catalog 遷移至 package.json 中的 workspaces 欄位：

{
  "workspaces": {
    "packages": ["apps/*", "packages/*"],
    "catalog": {
      "react": "^18.0.0",
      "typescript": "^5.0.0"
    },
    "catalogs": {
      "build": {
        "webpack": "^5.0.0",
        "babel": "^7.0.0"
      }
    }
  }
}

目錄相依

Bun 會保留使用 pnpm catalog: 協議的相依：

{
  "dependencies": {
    "react": "catalog:",
    "webpack": "catalog:build"
  }
}

設定遷移

Bun 會從 pnpm-lock.yaml 和 pnpm-workspace.yaml 中遷移以下 pnpm 設定：

• overrides 從 pnpm.overrides 遷移至 package.json 根級 overrides
• patchedDependencies 從 pnpm.patchedDependencies 遷移至 package.json 根級 patchedDependencies
• workspace overrides 應用自 pnpm-workspace.yaml 至根 package.json

要求和限制

• 要求 pnpm 鎖檔案版本為 7 或更高
• 工作區包的 package.json 中必須包含 name 欄位
• 相依引用的所有 catalog 條目都必須存在於 catalogs 定義中
• pnpm-lock.yaml 中的每個工作區都必須在磁碟上有對應的 package.json（在 Docker 中，請在執行 bun install 之前將其複製進去）
• 不支援相對路徑的 link: 相依，以及帶有子目錄（resolution.path）的 git 相依
• 如果遷移因上述任一原因失敗，Bun 會列印原因，並改為從頭開始解析

遷移完成後，可以安全刪除 pnpm-lock.yaml 和 pnpm-workspace.yaml。

CLI 用法

bun install <name>@<version>

通用設定

相依範圍與管理

相依型別與版本控制

鎖檔案控制

網路與登錄檔設定

安裝過程控制

快取選項

輸出與日誌記錄

安全與完整性

並行與效能

生命週期指令碼管理

幫助資訊