pnpm 幽灵依赖是什么？从 npm 迁移到 pnpm 后报 Cannot find module 怎么办？

Question

仓乃文 · Accepted Answer

从 npm 迁移到 pnpm 后最常见的报错就是 Cannot find module，代码明明没改，本地 npm 能跑，pnpm 就炸了。这不是 pnpm 的 Bug，而是 npm 掩盖了你的 Bug——幽灵依赖。

什么是幽灵依赖：
```
你的 package.json 只声明了 express，但 express 依赖了 cookie。

npm 的扁平化安装：
node_modules/
├── express/       ← 你声明的
├── cookie/        ← 被提升上来了！你能直接 require("cookie")
└── body-parser/   ← 也被提升了

pnpm 的严格隔离：
node_modules/
├── .pnpm/         ← 所有依赖的真实存储
│   ├── express@4.18.0/
│   │   └── node_modules/
│   │       ├── express/
│   │       └── cookie/   ← 只 express 能访问
│   └── cookie@1.0.0/
├── express -> .pnpm/express@4.18.0/node_modules/express
└── （没有 cookie！）  ← 没声明就访问不到
```

npm 允许你 import 未声明的依赖（因为扁平化提升了），pnpm 严格禁止。代码中直接 import 了未在 package.json 中声明的包，就是幽灵依赖。

排查幽灵依赖：
```bash
# 1. 找到代码中 import 了哪些未声明的包
npx depcheck
# 会列出未声明但被使用的包

# 2. 查看具体哪些文件用了幽灵依赖
npx depcheck --json | jq ".missing"
```

修复方案：
```bash
# 方案 1：显式安装缺失依赖（推荐）
pnpm add cookie body-parser
# 把代码中直接 import 的包都声明到 package.json

# 方案 2：临时兼容（迁移期过渡）
echo "shamefully-hoist=true" > .npmrc
# 模拟 npm 的扁平化，但失去了 pnpm 的严格性

# 方案 3：只提升特定包
# .npmrc
public-hoist-pattern[]=*eslint*
public-hoist-pattern[]=*prettier*
public-hoist-pattern[]=*babel*
```

迁移步骤：
```bash
# 1. 删除旧的 node_modules 和 lockfile
rm -rf node_modules package-lock.json yarn.lock

# 2. 用 depcheck 检查幽灵依赖
npx depcheck

# 3. 显式安装所有缺失的依赖
pnpm add <缺失的包名>

# 4. pnpm install
pnpm install

# 5. 验证项目能正常运行
pnpm dev && pnpm build && pnpm test
```

补充说明：
- 幽灵依赖是 npm 的设计缺陷，不是 pnpm 的问题
- 规则：代码中 import 了什么，package.json 就必须声明什么
- shamefully-hoist 只是过渡方案，不要长期使用
- 迁移前先用 depcheck 扫一遍，比运行时报错再修效率高 10 倍
- pnpm 的严格依赖是优势，它帮你提前发现问题