Skip to main content
Bun 提供了一种名为 隔离安装 的替代软件包安装策略，可创建类似于 pnpm 方法的严格依赖隔离。此模式可防止幽灵依赖（导入自身未声明依赖的软件包），并使构建过程可复现且具有确定性。 对于新建的工作区/monorepo 项目（锁文件中包含 configVersion = 1），隔离安装是默认方式。除非进行显式配置，否则现有项目会继续使用提升式安装。

​
什么是隔离安装？

隔离安装创建了非提升的依赖结构，包只能访问它们显式声明的依赖。这有别于 npm 和 Yarn 传统的“提升”安装策略，即依赖项被扁平化到共享的 node_modules 目录中。

​
主要优点

  • 防止幻影依赖 — 包不能意外导入未声明的依赖
  • 确定性解析 — 无论安装了什么，依赖树相同
  • 更适合多包仓库 — 工作区隔离防止包之间的交叉污染
  • 可复现构建 — 在不同环境下解析行为更可预测。

​
使用隔离安装

​
命令行

使用 --linker 标志指定安装策略：
terminal

​
配置文件

在你的 bunfig.toml 或全局 $HOME/.bunfig.toml 中设置默认 linker 策略：
bunfig.toml

​
默认行为

默认 linker 策略取决于项目锁文件的 configVersion： 新项目：默认为 configVersion = 1。工作区中，v1 默认使用隔离 linker；否则使用提升链接。 已有 Bun 项目（v1.3.2 之前创建）：如果现有锁文件未标明版本，运行 bun install 时 Bun 会将 configVersion 设为 0，保持之前的提升 linker 默认。 从其他包管理器迁移：
  • 来自 pnpm：configVersion = 1（工作区中使用隔离安装）
  • 来自 npm 或 yarn：configVersion = 0（使用提升安装）
通过传递 --linker 标志或在配置文件中设置来覆盖默认值。

​
隔离安装如何工作

​
目录结构

隔离安装不提升依赖，而是创建两层结构：
tree layout of node_modules

​
解析算法

  1. 中央仓库 — 所有包安装在 node_modules/.bun/package@version/ 目录中
  2. 符号链接 — 顶层 node_modules 包包含指向中央仓库的符号链接
  3. Peer 解析 — 复杂的 peer 依赖使用特殊目录名
  4. 去重 — 具有相同包 ID 和 peer 依赖集的包被共享

​
工作区处理

在多包仓库中，工作区依赖有特殊处理：
  • 工作区包 — 直接链接到其源目录，而不是存储目录
  • 工作区依赖 — 可以访问 monorepo 中的其他工作区包
  • 外部依赖 — 安装在隔离存储中

​
与提升安装的比较

​
高级功能

​
对等依赖处理

隔离安装会将对等依赖编码到存储路径中：
tree layout of node_modules
目录名称同时包含包版本及其对等依赖版本，因此每种唯一组合都会获得自己的安装。

​
全局虚拟存储

当启用 install.globalStore 时，存储条目会先物化一次到 <cache>/links/ 下的 全局虚拟存储，而 node_modules/.bun/<pkg>@<ver> 则是指向它的符号链接。在 rm -rf node_modules 之后进行冷启动安装时，每个包只需创建一个符号链接，而不是再次复制每个包的文件，这在典型的中型项目中大约快 7×。全局存储默认关闭；请参阅 全局存储文档 了解如何启用、完整布局、基准测试和权衡。

​
后端策略

当全局存储被禁用（默认）或某个条目不适合使用时，Bun 会使用以下方式之一将条目物化到项目中：
  • Clonefile（macOS）— 写时复制文件系统克隆
  • Hardlink（Linux/Windows）— 用于节省磁盘空间的硬链接
  • Copyfile（回退方案）— 在其他方法不可用时复制完整文件

​
调试隔离安装

启用详细日志记录以查看安装过程：
terminal
详细输出会显示：
  • 存储条目创建
  • 符号链接操作
  • 对等依赖解析
  • 去重决策

​
故障排除

​
兼容性问题

一些包可能不兼容隔离安装，原因包括：
  • 硬编码路径 — 假设 node_modules 结构扁平
  • 动态导入 — 运行时导入不遵循 Node.js 解析
  • 构建工具 — 直接扫描 node_modules
遇到问题时可：
  1. 对特定项目切换回提升模式：
    terminal
  2. 报告兼容性问题，帮助改进隔离安装支持

​
性能考虑

  • 安装时间 — 可能略慢，因符号链接操作
  • 磁盘使用 — 与提升类似（使用符号链接，不复制文件）
  • 内存使用 — 因复杂 peer 解析，安装时更高。

​
迁移指南

​
从 npm/Yarn 迁移

terminal

​
从 pnpm 迁移

隔离安装在概念上与 pnpm 类似，因此迁移是直接的：
terminal
主要差别是 Bun 在 node_modules 中使用符号链接，而 pnpm 使用全局存储与符号链接。

​
何时使用隔离安装

适合使用隔离安装的情况：
  • 在多包仓库中工作
  • 需要严格依赖管理
  • 需要防止幻影依赖
  • 构建需依赖确定性的库
适合使用提升安装的情况：
  • 使用假设扁平 node_modules 的旧代码
  • 需要兼容现有构建工具
  • 在符号链接支持不佳环境中工作
  • 喜欢传统 npm 简单行为。

​
相关文档