Skip to main content
Bun 提供了一种称为隔离安装的替代包安装策略，它创建严格的依赖隔离，类似于 pnpm 的方法。这种模式可防止幽灵依赖并确保可重现、确定性的构建。 这是新工作区/单一代码库项目（锁文件中的 configVersion = 1）的默认安装策略。现有项目继续使用提升安装，除非明确配置。

​
什么是隔离安装？

隔离安装创建一个非提升的依赖结构，包只能访问其明确声明的依赖。这不同于 npm 和 Yarn 使用的传统”提升”安装策略，其中依赖被扁平化到共享的 [node_modules] 目录中。

​
主要优点

  • 防止幽灵依赖 — 包不能意外导入它们未声明的依赖
  • 确定性解析 — 无论安装了什么其他内容，依赖树都相同
  • 更适合单一代码库 — 工作区隔离防止包之间的交叉污染
  • 可重现的构建 — 跨环境的解析行为更加可预测

​
使用隔离安装

​
命令行

使用 --linker 标志指定安装策略：
terminal
# 使用隔离安装
bun install --linker isolated

# 使用传统的提升安装
bun install --linker hoisted

​
配置文件

在你的 [bunfig.toml] 中或全局在 $HOME/.bunfig.toml 中设置默认链接器策略：
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 标志或在配置文件中设置来覆盖默认行为。

​
隔离安装的工作原理

​
目录结构

而不是提升依赖，隔离安装创建两层结构：
tree layout of node_modules
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. 同级解析 — 复杂的同级依赖创建专门的目录名称
  4. 去重 — 具有相同包 ID 和同级依赖集合的包被共享

​
工作区处理

在单一代码库中，工作区依赖被特殊处理：
  • 工作区包 — 直接符号链接到其源目录，而不是存储
  • 工作区依赖 — 可以访问单一代码库中的其他工作区包
  • 外部依赖 — 在隔离存储中安装并正确隔离

​
与提升安装的比较

方面提升（npm/Yarn）隔离（类似 pnpm）
依赖访问包可以访问任何提升的依赖包只能看到声明的依赖
幽灵依赖❌ 可能发生✅ 防止
磁盘使用✅ 更低（共享安装）✅ 相似（使用符号链接）
确定性❌ 较少确定✅ 更多确定
Node.js 兼容性✅ 标准行为✅ 通过符号链接兼容
最适合单个项目，遗留代码单一代码库，严格的依赖管理

​
高级特性

​
同级依赖处理

隔离安装通过复杂的解析处理同级依赖：
tree layout of node_modules
# 具有同级依赖的包创建专门的路径
node_modules/.bun/package@1.0.0_react@18.2.0/
目录名称同时编码包版本及其同级依赖版本，确保每个唯一组合都有自己的安装。

​
后端策略

Bun 使用不同的文件操作策略来提高性能：
  • Clonefile (macOS) — 写时复制文件系统克隆以实现最大效率
  • Hardlink (Linux/Windows) — 硬链接以节省磁盘空间
  • Copyfile (备用) — 当其他方法不可用时的完整文件副本

​
调试隔离安装

启用详细日志记录以了解安装过程：
terminal
bun install --linker isolated --verbose
这显示：
  • 存储条目创建
  • 符号链接操作
  • 同级依赖解析
  • 去重决策

​
故障排除

​
兼容性问题

由于以下原因，某些包可能无法与隔离安装正确工作：
  • 硬编码路径 — 假设平面 [node_modules] 结构的包
  • 动态导入 — 不遵循 Node.js 解析的运行时导入
  • 构建工具 — 直接扫描 [node_modules] 的工具
如果你遇到问题，你可以：
  1. 对特定项目切换到提升模式：
    terminal
    bun install --linker hoisted
  2. 报告兼容性问题 以帮助改进隔离安装支持

​
性能注意事项

  • 安装时间 — 由于符号链接操作可能会稍微慢一些
  • 磁盘使用 — 与提升类似（使用符号链接，而非文件副本）
  • 内存使用 — 安装期间由于复杂的同级解析而更高

​
迁移指南

​
从 npm/Yarn

terminal
# 删除现有的 node_modules 和锁文件
rm -rf node_modules package-lock.json yarn.lock

# 使用隔离链接器安装
bun install --linker isolated

​
从 pnpm

隔离安装在概念上类似于 pnpm，因此迁移应该很简单：
terminal
# 删除 pnpm 文件
rm -rf node_modules pnpm-lock.yaml

# 使用 Bun 的隔离链接器安装
bun install --linker isolated
主要区别在于 Bun 在 [node_modules] 中使用符号链接，而 pnpm 使用带有符号链接的全局存储。

​
何时使用隔离安装

在以下情况下使用隔离安装：
  • 在具有多个包的单一代码库中工作
  • 需要严格的依赖管理
  • 防止幽灵依赖很重要
  • 构建需要确定性依赖的库
在以下情况下使用提升安装：
  • 处理假定平面 [node_modules] 的遗留代码
  • 需要与现有构建工具兼容
  • 在不很好地支持符号链接的环境中工作
  • 你喜欢简单的传统 npm 行为

​
相关文档