Bun 提供了一種稱為 隔離安裝（isolated installs）的替代包安裝策略，它創建了類似於 pnpm 方法的嚴格依賴隔離。此模式防止幻象依賴並確保可重現、確定性的構建。

這是 新 工作區/monorepo 項目（鎖文件中 configVersion = 1）的默認安裝策略。現有項目繼續使用提升安裝，除非明確配置。

什麼是隔離安裝？

隔離安裝創建了一個非提升的依賴結構，包只能訪問其明確聲明的依賴。這與 npm 和 Yarn 使用的傳統"提升"安裝策略不同，後者將依賴扁平化到共享的 node_modules 目錄中。

主要優勢

• 防止幻象依賴 — 包不能意外導入它們未聲明的依賴
• 確定性解析 — 無論還安裝了什麼，依賴樹都相同
• 更適合 monorepo — 工作區隔離防止包之間的交叉污染
• 可重現的構建 — 跨環境的行為更可預測

使用隔離安裝

命令行

使用 --linker 標志指定安裝策略：

# 使用隔離安裝
bun install --linker isolated

# 使用傳統提升安裝
bun install --linker hoisted

配置文件

在 bunfig.toml 或 $HOME/.bunfig.toml 中設置默認鏈接器策略：

[install]
linker = "isolated"

默認行為

默認鏈接器策略取決於項目的鎖文件 configVersion：

configVersion	使用工作區？	默認鏈接器
1	✅	isolated
1	❌	hoisted
0	✅	hoisted
0	❌	hoisted

新項目：默認為 configVersion = 1。在工作區中，v1 默認使用隔離鏈接器；否則使用提升鏈接。

現有 Bun 項目（v1.3.2 之前創建）：如果你的現有鎖文件還沒有版本，當你運行 bun install 時，Bun 會設置 configVersion = 0，保留之前的提升鏈接器默認值。

從其他包管理器遷移：

• 從 pnpm：configVersion = 1（在工作區中使用隔離安裝）
• 從 npm 或 yarn：configVersion = 0（使用提升安裝）

你可以通過顯式指定 --linker 標志或在配置文件中設置來覆蓋默認行為。

隔離安裝的工作原理

目錄結構

隔離安裝不是提升依賴，而是創建雙層結構：

node_modules/
├── .bun/                          # 中央包存儲
│   ├── package@1.0.0/             # 版本化包安裝
│   │   └── node_modules/
│   │       └── package/           # 實際包文件
│   ├── @scope+package@2.1.0/      # 作用域包（+ 替換 /）
│   │   └── node_modules/
│   │       └── @scope/
│   │           └── package/
│   └── ...
└── package-name -> .bun/package@1.0.0/node_modules/package  # 符號鏈接

解析算法

1. 中央存儲 — 所有包都安裝在 node_modules/.bun/package@version/ 目錄中
2. 符號鏈接 — 頂層 node_modules 包含指向中央存儲的符號鏈接
3. peer 解析 — 復雜的 peer 依賴創建專門的目錄名稱
4. 去重 — 具有相同包 ID 和 peer 依賴集的包會被共享

工作區處理

在 monorepo 中，工作區依賴的處理方式特殊：

• 工作區包 — 直接符號鏈接到它們的源目錄，而不是存儲
• 工作區依賴 — 可以訪問 monorepo 中的其他工作區包
• 外部依賴 — 安裝在隔離存儲中，具有適當的隔離

與提升安裝的比較

方面	提升（npm/Yarn）	隔離（類似 pnpm）
依賴訪問	包可以訪問任何提升的依賴	包只能看到聲明的依賴
幻象依賴	❌ 可能	✅ 防止
磁盤使用	✅ 較低（共享安裝）	✅ 類似（使用符號鏈接）
確定性	❌ 較不確定	✅ 更確定
Node.js 兼容性	✅ 標准行為	✅ 通過符號鏈接兼容
最適合	單個項目、遺留代碼	monorepo、嚴格的依賴管理

高級功能

Peer 依賴處理

隔離安裝通過復雜的解析處理 peer 依賴：

# 具有 peer 依賴的包創建專門的路徑
node_modules/.bun/package@1.0.0_react@18.2.0/

目錄名稱編碼了包版本及其 peer 依賴版本，確保每個唯一組合都有自己的安裝。

後端策略

Bun 使用不同的文件操作策略來提高性能：

• Clonefile（macOS）— 寫時復制文件系統克隆以實現最大效率
• Hardlink（Linux/Windows）— 硬鏈接以節省磁盤空間
• Copyfile（回退）— 當其他方法不可用時進行完整文件復制

調試隔離安裝

啟用詳細日志以了解安裝過程：

bun install --linker isolated --verbose

這將顯示：

• 存儲條目創建
• 符號鏈接操作
• peer 依賴解析
• 去重決策

故障排除

兼容性問題

某些包可能無法與隔離安裝正常工作，原因包括：

• 硬編碼路徑 — 假設扁平 node_modules 結構的包
• 動態導入 — 不遵循 Node.js 解析的運行時導入
• 構建工具 — 直接掃描 node_modules 的工具

如果遇到問題，你可以：

1. 為特定項目切換到提升模式：

   bun install --linker hoisted

2. 報告兼容性問題 以幫助改進隔離安裝支持

性能考慮

• 安裝時間 — 由於符號鏈接操作，可能稍慢
• 磁盤使用 — 與提升類似（使用符號鏈接，而不是文件復制）
• 內存使用 — 由於復雜的 peer 解析，安裝期間較高

遷移指南

從 npm/Yarn

# 刪除現有的 node_modules 和鎖文件
rm -rf node_modules package-lock.json yarn.lock

# 使用隔離鏈接器安裝
bun install --linker isolated

從 pnpm

隔離安裝在概念上類似於 pnpm，因此遷移應該很簡單：

# 刪除 pnpm 文件
rm -rf node_modules pnpm-lock.yaml

# 使用 Bun 的隔離鏈接器安裝
bun install --linker isolated

主要區別在於 Bun 在 node_modules 中使用符號鏈接，而 pnpm 使用帶有符號鏈接的全局存儲。

何時使用隔離安裝

使用隔離安裝的情況：

• 在具有多個包的 monorepo 中工作
• 需要嚴格的依賴管理
• 防止幻象依賴很重要
• 構建需要確定性依賴的庫

使用提升安裝的情況：

• 使用假設扁平 node_modules 的遺留代碼
• 需要與現有構建工具兼容
• 在符號鏈接支持不佳的環境中工作
• 你更喜歡更簡單的傳統 npm 行為

相關文檔

• 包管理器 > 工作區 — monorepo 工作區管理
• 包管理器 > 鎖文件 — 了解 Bun 的鎖文件格式
• CLI > install — 完整的 bun install 命令參考