隔离安装

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  # 符号链接

解析算法

中央存储 — 所有包安装在 node_modules/.bun/package@version/ 目录中
符号链接 — 顶层 node_modules 包含指向中央存储的符号链接
对等解析 — 复杂的对等依赖创建专门的目录名称
去重 — 具有相同包 ID 和对等依赖集的包被共享

工作空间处理

在单体仓库中，工作空间依赖被特殊处理：

工作空间包 — 直接符号链接到其源目录，而非存储
工作空间依赖 — 可以访问单体仓库中的其他工作空间包
外部依赖 — 安装在隔离存储中

与提升安装的对比

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

高级特性

对等依赖处理

隔离安装将对等依赖编码到存储路径中：

tree layout of node_modules

# 带有对等依赖的包创建专门的路径
node_modules/.bun/package@1.0.0_react@18.2.0/

目录名称包含包版本及其对等依赖版本，因此每个唯一组合都有自己的安装。

全局虚拟存储

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

后端策略

当全局存储禁用（默认）或条目不符合条件时，Bun 使用以下之一在项目下物化条目：

Clonefile（macOS）— 写时复制的文件系统克隆
Hardlink（Linux/Windows）— 硬链接以节省磁盘空间
Copyfile（回退）— 其他方法不可用时的完整文件复制

调试隔离安装

启用详细日志记录以查看安装正在做什么：

terminal

bun install --linker isolated --verbose

详细输出显示：

存储条目的创建
符号链接操作
对等依赖解析
去重决策

故障排除

兼容性问题

某些包可能无法与隔离安装正常工作，原因包括：

硬编码路径 — 假设扁平 node_modules 结构的包
动态导入 — 不遵循 Node.js 解析规则的运行时导入
构建工具 — 直接扫描 node_modules 的工具

如果遇到问题，你可以：

为特定项目切换到提升模式：
terminal
bun install --linker hoisted
报告兼容性问题以帮助改进隔离安装支持

性能考虑

安装时间 — 由于符号链接操作，可能稍慢
磁盘使用 — 与提升类似（使用符号链接，而非文件复制）
内存使用 — 由于复杂的对等解析，安装期间更高

迁移指南

从 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 行为

核心命令

发布与分析

工作空间管理

高级配置

什么是隔离安装？

主要优势

使用隔离安装

命令行

配置文件

默认行为

隔离安装的工作原理

目录结构

解析算法

工作空间处理

与提升安装的对比

高级特性

对等依赖处理

全局虚拟存储

后端策略

调试隔离安装

故障排除

兼容性问题

性能考虑

迁移指南

从 npm/Yarn

从 pnpm

何时使用隔离安装

相关文档

​什么是隔离安装？

​主要优势

​使用隔离安装

​命令行

​配置文件

​默认行为

​隔离安装的工作原理

​目录结构

​解析算法

​工作空间处理

​与提升安装的对比

​高级特性

​对等依赖处理

​全局虚拟存储

​后端策略

​调试隔离安装

​故障排除

​兼容性问题

​性能考虑

​迁移指南

​从 npm/Yarn

​从 pnpm

​何时使用隔离安装

​相关文档

什么是隔离安装？

主要优势

使用隔离安装

命令行

配置文件

默认行为

隔离安装的工作原理

目录结构

解析算法

工作空间处理

与提升安装的对比

高级特性

对等依赖处理

全局虚拟存储

后端策略

调试隔离安装

故障排除

兼容性问题

性能考虑

迁移指南

从 npm/Yarn

从 pnpm

何时使用隔离安装

相关文档