pnpm 与 npm 对比：安装机制、磁盘占用、依赖隔离与迁移指南

每个项目都把依赖**完整复制**一份到自己的 node_modules 里，相同版本的包会被重复存放。 **示例**：3 个项目都依赖 `lodash@4.17.21`，npm 会在 3 处各存一份（约 3 × 1.4MB）。

相同版本的依赖在「多个项目之间」和「多层依赖之间」反复复制。 **示例**：10 个项目都含 React 生态，npm 可能占用数 GB 磁盘，而这些包内容完全相同。

每次安装基本是「解压 + 复制」全量工作，即使命中缓存也有磁盘写入开销。 **场景**：首次安装或 CI 冷缓存时更慢，多项目环境差距明显。

扁平化把传递依赖也提升到顶层，导致**未在 package.json 声明**的包也能被直接 import —— 即「幽灵依赖」。 **示例**：你没写 `lodash`，但因某个依赖引入了它，`import lodash from 'lodash'` 居然能跑；一旦那个依赖升级/移除，代码立刻报错。换包管理器时最容易踩这个坑。

依赖尽量「提升」到顶层，层级被压平，同名不同版本易冲突。 **示例**：`node_modules/lodash` 与 `node_modules/express/node_modules/lodash` 混在一起，靠嵌套目录来隔离冲突版本，结构较乱。

记录完整依赖树，锁定版本与来源。配合 `npm ci` 可做到确定性、可复现安装（CI 推荐）。

Node 官方自带，几乎所有工具、CI、脚手架默认支持；不使用符号链接，Windows 和老旧工具链都无兼容顾虑。

**全局内容寻址存储** pnpm 把所有包按内容哈希存到全局 store（如 `~/.pnpm-store`），项目里的 `node_modules` 通过**硬链接**指向 store 中的文件，而不是真正复制。 **实例** - 同一版本 lodash 被 10 个项目使用，磁盘上**只有一份**，其余都是硬链接。 - 升级依赖时，只有变化的文件重新写入 store。 **效果**：安装接近「建立链接」，快且省空间。

**同一版本只存一份** 因为硬链接复用全局 store，多个项目共享同一份包文件。 **实例** - 3 个项目都用 react@18：npm 存 3 份，pnpm 存 1 份 + 3 组链接。 - 大型 Monorepo 里常见节省 **数 GB** 磁盘。 **注意**：跨文件系统（如不同磁盘）时无法硬链接，pnpm 会自动退化为复制。

**通常更快** 复用 store 后免去大量重复下载与解压，热安装（store 已命中）尤其明显。 **实例** - 第二次安装同一项目：pnpm 常只需建立链接，秒级完成。 - CI 中配置 pnpm store 缓存后，安装时间可显著下降。 **说明**：冷安装（空 store）需先填充 store，优势主要在重复场景与多项目环境。

**只能访问已声明的包** `node_modules` 是严格嵌套的：只有 `package.json` 里声明的依赖才会出现在可直接引用的位置，未声明的包**无法 import**。 **实例** - 未声明却 `import 'lodash'` 会直接报错 `Cannot find module`，因为 npm 扁平化才「顺手」能用到。 **好处**：从源头杜绝幽灵依赖，避免上线后因依赖升级而突然报错。

**严格嵌套 + 符号链接** 真实包放在 `node_modules/.pnpm/<pkg>@<ver>/`，顶层 `node_modules` 只放**符号链接**指向它们。 **实例** ``` node_modules/ ├── lodash -> .pnpm/lodash@4.17.21/node_modules/lodash └── .pnpm/ └── lodash@4.17.21/ └── node_modules/lodash/ ``` 每个包只能访问自己依赖树里的包，结构即依赖关系的真实映射。

**pnpm-lock.yaml** YAML 格式，可读性好，额外记录包的**完整性哈希**与依赖关系快照。 **实例** ``` lockfileVersion: '9.0' importers: .: dependencies: react: {specifier: ^18.2.0, version: 18.3.1} ``` 配合 `pnpm install --frozen-lockfile` 可在 CI 中保证依赖完全一致。

**兼容性可用配置兜底** 部分老旧工具（如某些打包器、插件）依赖扁平化结构，会读不到嵌套包。 **兼容示例** 在 `.npmrc` 中： ``` node-linker=hoisted ``` 即可让 pnpm 生成类似 npm 的扁平 `node_modules`。 **实例**：老版本 React Native / 部分 CLI 工具需要此配置才能正常运行。

一句话总结

**npm：复制式安装** - 安装时把每个依赖（含其依赖）**实体复制**到本项目的 `node_modules`。 - 为提升查找效率，npm 3+ 将目录**扁平化**：所有包尽量平铺到顶层，冲突时才嵌套。 - 代价：同一个包在 10 个项目里就存 10 份，磁盘膨胀；扁平化让代码能访问未声明的包。 **幽灵依赖实例** ```js // 只在 package.json 声明了 A，A 依赖 B import B from 'b'; // npm 下往往能跑通（B 被提升到顶层） // 一旦 A 升级不再依赖 B，构建立刻崩 ``` > 结论：拷进来、平铺放，简单直接但浪费空间、依赖边界模糊。

**pnpm：链接式安装** - 所有包版本统一存进**全局内容寻址存储**（`~/.pnpm-store`），按内容哈希索引。 - 项目 `node_modules` 里放的是指向存储的**硬链接**；对上层依赖则用**符号链接**组织。 - 目录严格对应依赖树：**只有声明过的包才能被访问**。 **结构实例** ``` node_modules/ ├── .pnpm/ # 真实文件（硬链接到全局存储） │ └── b@2.0.0/node_modules/b └── a -> .pnpm/a@1.0.0/node_modules/a # 符号链接 ``` `import B from 'b'` 若 B 未声明会直接报错，杜绝幽灵依赖。 > 结论：全局存一份、链接复用，省空间且依赖边界严格。

**从 npm 切到 pnpm** ```bash rm -rf node_modules package-lock.json pnpm install # 生成新的 pnpm-lock.yaml ``` **注意事项** - 团队成员需统一使用 pnpm，**不要混用锁文件**（否则版本漂移）。 - 在 `package.json` 加 `"packageManager": "pnpm@9"` 约束版本。 - 老工具链兼容问题：新建 `.npmrc` 写入 ``` node-linker=hoisted ``` 即可退回扁平结构（会失去严格隔离，仅作过渡）。 - 反向切回 npm 同理：删掉 `node_modules` 与 `pnpm-lock.yaml` 再 `npm install`。