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 命令参考