什么是幽灵依赖？#

由于模块被提升到了顶层，开发者可以在代码中直接 import 那些并未在 package.json 中显式声明的库。

1
{
2
  "dependencies": {
3
    "express": "^4.18.0"
4
  }
5
}

1
// 开发者可以直接导入 body-parser，因为它是 express 的依赖，被提升到了顶层
2
import bodyParser from 'body-parser';

风险点：

1. 不可靠性：一旦 express 在升级时移除了对 body-parser 的依赖，你的项目会立即在本地或 CI 环境中报错。
2. 版本冲突：如果项目中有多个库依赖了不同版本的同一个间接依赖，提升机制可能会导致版本覆盖，引发难以排查的 Bug。

pnpm 的 node_modules 布局#

当你使用 pnpm 安装依赖时，根目录的 node_modules 仅包含你在 package.json 中声明的包。这些包实际上是到 .pnpm 目录下的软链接。

1
node_modules
2
├── express -> .pnpm/express@4.18.0/node_modules/express
3
└── .pnpm
4
    ├── express@4.18.0
5
    │   └── node_modules
6
    │       ├── express (实际文件或硬链接)
7
    │       └── body-parser -> ../../body-parser@1.20.0/node_modules/body-parser
8
    └── body-parser@1.20.0
9
        └── node_modules
10
            └── body-parser

graph TD
    Root["项目根目录/node_modules"]
    ExpressLink["express (Symlink)"]
    PnpmStore[".pnpm 虚拟存储区"]
    ExpressReal["express@4.18.0/node_modules/express"]
    BPReal["body-parser@1.20.0/node_modules/body-parser"]
    GlobalStore[("全局内容寻址存储 (~/.pnpm-store)")]

    Root --> ExpressLink
    ExpressLink -.-> ExpressReal
    ExpressReal -->|依赖| BPReal
    ExpressReal -->|硬链接| GlobalStore
    BPReal -->|硬链接| GlobalStore

核心优势#

1. 严格限制访问：由于根目录 node_modules 下没有 body-parser，代码中 import 'body-parser' 会直接报错。这强制开发者必须显式声明依赖。
2. 解决多版本冗余：在扁平化结构中，如果一个包无法被提升（版本冲突），它会被多次安装。pnpm 通过全局 Store 确保同一个文件在磁盘上只存在一份。
3. 极速安装：由于使用了硬链接，安装过程主要是创建链接的操作，速度显著优于 npm/yarn。

4.1 兼容“幽灵依赖”：shamefully-hoist#

很多老旧的 Webpack 插件（如 eslint-plugin-* 或某些 Babel preset）在内部硬编码了寻找子依赖的逻辑，或者默认其子依赖一定会被提升到根目录。

在迁移 pnpm 时，这些工具往往会报 Module not found。作为临时过渡方案，你可以配置 .npmrc 放宽隔离限制：

1
# 创建半隔离的提升结构，让不规范的第三方包能找到依赖
2
shamefully-hoist=true

但请注意，这是饮鸩止渴。长期来看，应该通过显式声明依赖或使用 packageExtensions 来彻底解决：

1
// package.json (pnpm 的补丁机制)
2
"pnpm": {
3
  "packageExtensions": {
4
    "bad-webpack-plugin@1.0.0": {
5
      "peerDependencies": {
6
        "webpack": "^4.0.0"
7
      }
8
    }
9
  }
10
}

4.2 Peer Dependencies 的严格校验#

在 npm/Yarn 中，如果 A 依赖 React 17，B 依赖 React 18，包管理器可能会强行提升一个版本，导致另一个组件在运行时崩溃。

pnpm 处理 peerDependencies 的策略极其严格：它会为不同的 Peer 依赖组合，创建不同的虚拟实例。

例如，如果两个不同的包同时依赖了 button-ui，但提供了不同版本的 react 作为 peer：

1
.pnpm
2
├── button-ui@1.0.0(react@17.0.2)
3
└── button-ui@1.0.0(react@18.2.0)

pnpm 会在 .pnpm 目录下创建两个 独立的硬链接实例。这完美解决了 React Hooks 中的 Invalid hook call（通常由于项目中存在多个 React 实例导致）问题。

但这也意味着，在开发 Monorepo 组件库时，如果你没有在子包中正确声明 peerDependencies，pnpm 绝对不会像 Yarn 那样“默默帮你找齐”，而是直接抛出错误。这就倒逼开发者必须保证依赖声明的绝对严谨。