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