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 中设置默认 linker 策略：
bunfig.toml
[install]
linker = "isolated"

​
默认行为

默认 linker 策略取决于项目锁文件的 configVersion：
configVersion是否使用工作区？默认 Linker
1✅isolated
1❌hoisted
0✅hoisted
0❌hoisted
新项目：默认为 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
node_modules/
├── .bun/                          # 中央包存储
│   ├── [email protected]/             # 版本化包安装
│   │   └── node_modules/
│   │       └── package/           # 实际包文件
│   ├── @[email protected]/      # 作用域包 (+ 代替 /)
│   │   └── node_modules/
│   │       └── @scope/
│   │           └── package/
│   └── ...
└── package-name -> .bun/[email protected]/node_modules/package  # 符号链接

​
解析算法

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

​
工作区处理

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

​
与提升安装的比较

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

​
高级功能

​
Peer 依赖处理

隔离安装通过复杂解析处理 peer 依赖：
tree layout of node_modules
# 有 peer 依赖的包创建特化路径
node_modules/.bun/[email protected][email protected]/
目录名编码了包版本和其 peer 依赖版本，确保每种唯一组合都有自己的安装。

​
后端策略

Bun 使用不同文件操作策略提升性能：
  • Clonefile（macOS）— 复制时写入的文件系统克隆，效率最高
  • Hardlink（Linux/Windows）— 硬链接节省磁盘空间
  • Copyfile（回退方案）— 无其他方式时的完整文件复制

​
调试隔离安装

开启详细日志了解安装过程：
terminal
bun install --linker isolated --verbose
显示内容包括：
  • 存储条目创建
  • 符号链接操作
  • Peer 依赖解析
  • 去重决策

​
故障排除

​
兼容性问题

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

​
性能考虑

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

​
迁移指南

​
从 npm/Yarn 迁移

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

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

​
从 pnpm 迁移

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

# 使用 Bun 的隔离 linker 安装
bun install --linker isolated
主要差别是 Bun 在 node_modules 中使用符号链接，而 pnpm 使用全局存储与符号链接。

​
何时使用隔离安装

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

​
相关文档