什么是幽灵依赖？pnpm 如何解决这个问题？

什么是幽灵依赖？

幽灵依赖（Phantom Dependency）是指项目代码中引用了 package.json 未显式声明的包，它之所以能正常运行，完全是因为 npm/Yarn 的扁平化 node_modules 机制把间接依赖提升到了顶层。

为什么会产生幽灵依赖？

npm v2 之前使用嵌套安装，导致大量重复依赖和路径过长问题。npm v3 及 Yarn 改为扁平化策略：把所有依赖尽量提升到 node_modules 根目录。

bash
# package.json 只声明了 express
{
  "dependencies": {
    "express": "^4.18.0"
  }
}

# npm/Yarn 扁平化后的目录结构
node_modules/
├── express/        # 直接依赖
├── debug/          # express 的依赖，被提升到顶层
├── ms/             # debug 的依赖，也被提升
├── body-parser/    # express 的依赖，同样被提升
└── ...

Node.js 的模块查找算法会从当前目录逐级向上查找 node_modules，所以 require('debug') 能直接找到被提升上来的 debug 包，即使你从未声明过它。

幽灵依赖有什么危害？

javascript
// 代码中直接使用了未声明的 debug
const debug = require('debug');
// 能运行 —— 但这只是侥幸

// 风险场景：
// 1. express 某次升级后移除了对 debug 的依赖 → 你的代码直接报错
// 2. 另一位同事 clone 项目后 npm install → 可能安装到不同版本的 debug
// 3. CI 环境与本地依赖树不一致 → 构建时出现诡异失败
// 4. 安全审计工具不会标记未声明的包 → 漏洞无法被追踪

核心问题：依赖关系不完整记录 = 项目可复现性被破坏。

pnpm 如何解决幽灵依赖？

pnpm 通过两套机制彻底杜绝幽灵依赖：

1. 内容寻址存储 + 硬链接

pnpm 在全局维护一个 .store 目录，所有包只存一份。项目中的 node_modules 通过硬链接指向 store，同一台机器上无论多少个项目共享同一版本的包，磁盘上只有一份内容。

2. 符号链接隔离结构

pnpm 的 node_modules 结构与传统扁平化截然不同：

bash
node_modules/
├── .pnpm/
│   └── express@4.18.2/
│       └── node_modules/
│           ├── express/          # express 的实际内容
│           └── debug/            # express 自己能访问的依赖
│               └── node_modules/
│                   └── ms/       # debug 的依赖，只对 debug 可见
├── express -> .pnpm/express@4.18.2/node_modules/express
# 注意：顶层只有 express，没有 debug、ms 等间接依赖

• 项目根目录的 node_modules 只有 package.json 中声明的包（通过符号链接指向 .pnpm）
• 每个包自己的 node_modules 只包含该包直接声明的依赖

javascript
// pnpm 下尝试访问幽灵依赖
const debug = require('debug');
// Error: Cannot find module 'debug'

// 解决方式：显式声明
// pnpm add debug

shamefully-hoist：过渡方案

pnpm 提供了 shamefully-hoist=true 配置，模拟 npm 的扁平化结构。它适用于那些尚未修复幽灵依赖的老项目，但不推荐作为长期方案——它本质上放弃了 pnpm 的隔离优势。

ini
# .npmrc
shamefully-hoist=true

npm/Yarn vs pnpm 对比

特性	npm/Yarn	pnpm
依赖访问范围	可访问所有被提升的包	只能访问显式声明的依赖
依赖隔离	弱，扁平化导致间接依赖暴露	强，符号链接实现严格隔离
幽灵依赖	常见且难以发现	从结构上杜绝
磁盘占用	每个项目独立存储	全局 store + 硬链接，多项目共享
安装速度	较慢	显著更快（硬链接免去重复下载）
依赖树一致性	不同环境可能不同	严格一致

面试追问要点

Q: 为什么从 npm 迁移到 pnpm 后项目会报错？ 因为项目之前依赖了幽灵依赖。npm 下能侥幸运行，pnpm 的严格隔离直接暴露了这些未声明的依赖。修复方式是逐一 pnpm add 把缺失的依赖显式添加到 package.json。

Q: pnpm 的 .pnpm 目录结构如何保证依赖隔离？ 每个包在 .pnpm 下拥有独立的 node_modules 子树，其中只包含该包自身声明的依赖。Node.js 的模块查找算法在当前包的 node_modules 内就能找到所需依赖，不会向上穿透到其他包的作用域。

Q: 如果不使用 pnpm，如何检测幽灵依赖？ 可以使用 npx depcheck 工具扫描未声明但被使用的包，也可以在 npm 7+ 中开启 install-strategy=nested 改用嵌套安装来暴露问题。