> ## Documentation Index
> Fetch the complete documentation index at: https://bun.ll1025.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 隔离安装

> 类似 pnpm 的严格依赖隔离

Bun 提供了一种替代的包安装策略，称为**隔离安装**，它创建类似 pnpm 方式的严格依赖隔离。这种模式可以防止幽灵依赖（包导入其从未声明的依赖），并使构建具有可重复性和确定性。

隔离安装是**新的**工作空间/单体仓库项目的默认方式（锁文件中 `configVersion = 1`）。现有项目除非明确配置，否则继续使用提升安装。

## 什么是隔离安装？

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

### 主要优势

* **防止幽灵依赖** — 包无法意外导入其未声明的依赖
* **确定性解析** — 无论安装了什么其他内容，依赖树保持一致
* **更适合单体仓库** — 工作空间隔离防止包之间的交叉污染
* **可重复的构建** — 跨环境更可预测的解析行为

## 使用隔离安装

### 命令行

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

```bash terminal icon="terminal" theme={null}
# 使用隔离安装
bun install --linker isolated

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

### 配置文件

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

```toml bunfig.toml icon="settings" theme={null}
[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` 标志或在配置文件中设置来覆盖默认值。

## 隔离安装的工作原理

### 目录结构

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

```bash tree layout of node_modules icon="list-tree" theme={null}
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 兼容性** | ✅ 标准行为       | ✅ 通过符号链接兼容   |
| **最适合**         | 单个项目、遗留代码    | 单体仓库、严格依赖管理  |

## 高级特性

### 对等依赖处理

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

```bash tree layout of node_modules icon="list-tree" theme={null}
# 带有对等依赖的包创建专门的路径
node_modules/.bun/package@1.0.0_react@18.2.0/
```

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

### 全局虚拟存储

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

### 后端策略

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

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

### 调试隔离安装

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

```bash terminal icon="terminal" theme={null}
bun install --linker isolated --verbose
```

详细输出显示：

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

## 故障排除

### 兼容性问题

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

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

如果遇到问题，你可以：

1. **为特定项目切换到提升模式**：

   ```bash terminal icon="terminal" theme={null}
   bun install --linker hoisted
   ```

2. **报告兼容性问题**以帮助改进隔离安装支持

### 性能考虑

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

## 迁移指南

### 从 npm/Yarn

```bash terminal icon="terminal" theme={null}
# 删除现有的 node_modules 和锁文件
rm -rf node_modules package-lock.json yarn.lock

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

### 从 pnpm

隔离安装在概念上与 pnpm 相似，因此迁移是直接的：

```bash terminal icon="terminal" theme={null}
# 删除 pnpm 文件
rm -rf node_modules pnpm-lock.yaml

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

主要区别在于 Bun 使用 `node_modules` 中的符号链接，而 pnpm 使用带有符号链接的全局存储。

## 何时使用隔离安装

**在以下情况使用隔离安装：**

* 在具有多个包的单体仓库中工作
* 需要严格依赖管理
* 防止幽灵依赖很重要
* 构建需要确定性依赖的库

**在以下情况使用提升安装：**

* 使用假设扁平 `node_modules` 的遗留代码
* 需要与现有构建工具兼容
* 在符号链接支持不佳的环境中工作
* 你更喜欢更简单的传统 npm 行为

## 相关文档

* [包管理器 > 工作空间](/pm/workspaces) — 单体仓库工作空间管理
* [包管理器 > 锁文件](/pm/lockfile) — 理解 Bun 的锁文件格式
* [CLI > install](/pm/cli/install) — 完整的 `bun install` 命令参考