> ## Documentation Index
> Fetch the complete documentation index at: https://bun.zhcndoc.com/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={"theme":{"light":"github-light","dark":"dracula"}}
# 使用隔离安装
bun install --linker isolated

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

### 配置文件

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

```toml bunfig.toml icon="settings" theme={"theme":{"light":"github-light","dark":"dracula"}}
[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` 标志或在配置文件中设置来覆盖默认行为。

## 隔离安装如何工作

### 目录结构

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

```bash tree layout of node_modules icon="list-tree" theme={"theme":{"light":"github-light","dark":"dracula"}}
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 中的其他工作区包
* **外部依赖** — 安装在隔离存储中，保持正确隔离

## 与提升安装的比较

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

## 高级功能

### Peer 依赖处理

隔离安装通过复杂解析处理 peer 依赖：

```bash tree layout of node_modules icon="list-tree" theme={"theme":{"light":"github-light","dark":"dracula"}}
# 有 peer 依赖的包创建特化路径
node_modules/.bun/package@1.0.0_react@18.2.0/
```

目录名编码了包版本和其 peer 依赖版本，确保每种唯一组合都有自己的安装。

### Global virtual store

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

### 后端策略

当全局存储被禁用（默认）或某个条目不适合使用时，Bun 会使用以下方式之一将条目物化到项目中：

* **Clonefile**（macOS）— 复制时写入的文件系统克隆，效率最高
* **Hardlink**（Linux/Windows）— 硬链接节省磁盘空间
* **Copyfile**（回退方案）— 无其他方式时的完整文件复制

### 调试隔离安装

开启详细日志了解安装过程：

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
bun install --linker isolated --verbose
```

显示内容包括：

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

## 故障排除

### 兼容性问题

一些包可能不兼容隔离安装，原因包括：

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

遇到问题时可：

1. **对特定项目切换回提升模式：**

   ```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
   bun install --linker hoisted
   ```

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

### 性能考虑

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

## 迁移指南

### 从 npm/Yarn 迁移

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
# 删除现有 node_modules 和锁文件
rm -rf node_modules package-lock.json yarn.lock

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

### 从 pnpm 迁移

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

```bash terminal icon="terminal" theme={"theme":{"light":"github-light","dark":"dracula"}}
# 删除 pnpm 文件
rm -rf node_modules pnpm-lock.yaml

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

主要差别是 Bun 在 `node_modules` 中使用符号链接，而 pnpm 使用全局存储与符号链接。

## 何时使用隔离安装

**适合使用隔离安装的情况：**

* 在多包仓库中工作
* 需要严格依赖管理
* 需要防止幻影依赖
* 构建需依赖确定性的库

**适合使用提升安装的情况：**

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

## 相关文档

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