Skip to content
npm、yarn、pnpm 与 cnpm：node_modules 拓扑结构对比
概述
Node.js 生态中存在多个包管理器：npm、yarn、pnpm 以及主要解决网络可达性的 cnpm。它们的差异集中体现在 node_modules 目录的拓扑结构上——不同策略直接影响依赖解析的正确性、安装速度、磁盘占用，以及在 monorepo 场景下的可用性。
基本概念
npm 是 Node.js 早期内置的包管理器。当项目规模逐渐增大，npm 在安装速度、依赖确定性和离线支持方面的局限变得明显，社区陆续推出了替代方案：
- yarn（2016）针对 npm v3/v4 时期安装慢、lockfile 不可靠的问题，提供了确定性安装和离线缓存。
- pnpm（2017）进一步解决了 npm/yarn 扁平化
node_modules带来的幽灵依赖和磁盘冗余，核心思路是用硬链接和符号链接还原声明的依赖拓扑。 - cnpm 的出现则是为了解决国内网络环境下从 npm 官方 registry 下载慢甚至失败的问题，其本质是 npm 客户端加淘宝镜像源（
registry.npmmirror.com），每分钟从官方同步一次，并提供 Web 界面。随着官方源访问改善及nrm等工具的普及，独立 cnpm CLI 的使用已减少。
工作原理
扁平提升（npm 与 yarn classic）
当执行 npm install 或 yarn（v1）时，所有依赖尽可能提升到 node_modules 顶层，仅当版本冲突时才在子 node_modules 中嵌套：
node_modules/
├── A@1.0.0 ← 被提升到顶层
├── B@2.0.0 ← 被提升到顶层
├── C@1.0.0 ← 被提升到顶层
└── A/
└── node_modules/
└── D@1.0.0 ← 仅冲突的依赖保留在此这种做法的副作用是幽灵依赖：项目代码可以直接使用 require('C')，即使 package.json 中没有声明 C。只要某个直接依赖（例如 A）依赖了 C 且 C 被提升到顶层，它就对项目可见。
符号链接（pnpm）
pnpm 使用两层结构：全局 store 存放真实文件，项目 node_modules 中只有符号链接。
node_modules/
├── .pnpm/ ← 所有包的真实位置，硬链接到全局 store
│ ├── A@1.0.0/node_modules/ ← A 只能访问它声明的依赖
│ │ ├── D@1.0.0 → ../../D@1.0.0
│ │ └── B@2.0.0 → ../../B@2.0.0
│ ├── B@2.0.0/
│ ├── C@1.0.0/
│ └── D@1.0.0/
├── A → .pnpm/A@1.0.0/node_modules/A ← 只有直接依赖在这里
└── B → .pnpm/B@2.0.0/node_modules/B关键约束：
.pnpm/内每个包的node_modules只包含它显式声明的依赖。- 项目顶层
node_modules只出现package.json中列出的依赖。 - 真实文件通过硬链接指向全局 store（默认
~/.pnpm-store/）。
此时 require('C') 会抛出 MODULE_NOT_FOUND，因为 C 不在顶层符号链接中。这种方式从机制上杜绝了幽灵依赖。
Plug'n'Play（yarn Berry）
yarn 从 v2 开始引入 PnP 模式，直接抛弃 node_modules 目录：
项目根目录/
├── .pnp.cjs ← 依赖解析映射表
└── .yarn/
└── cache/ ← zip 格式缓存Node 通过 require('./pnp.cjs') 拦截模块解析，不再遍历 node_modules。安装几乎无文件 I/O，但要求工具链兼容 PnP 标准，部分老旧的包或构建工具可能无法工作。
示例
考虑项目 package.json：
json
{
"name": "demo",
"dependencies": {
"express": "^4.18.0"
}
}已知 express 依赖了 dayjs。在 npm 或 yarn classic 安装后，node_modules 顶层会出现 dayjs，因此以下代码可以运行：
javascript
const dayjs = require('dayjs');
console.log(dayjs());在 pnpm 安装后，顶层只存在 express 的符号链接，dayjs 深藏在 .pnpm/express@4.x.x/node_modules/ 中，上述代码会报错：
Error: Cannot find module 'dayjs'若要修复，必须在 package.json 中显式添加 dayjs 依赖。这一行为迫使项目明确列出所有直接依赖，避免隐藏的依赖链风险：当某天 express 不再使用 dayjs 时，依赖代码不会悄无声息地损坏。
行为对比
安装速度
| 场景 | npm | yarn classic | pnpm | yarn PnP |
|---|---|---|---|---|
| 冷安装（无缓存） | 慢 | 中 | 中 | 快 |
| 热安装（有缓存） | 中 | 中 | 快 | 极快 |
| CI/CD（有 lockfile） | 中 | 快 | 快 | 极快 |
pnpm 的热安装速度快，因为只需创建硬链接而无需复制文件。yarn PnP 极快，因为跳过了解压和目录生成。
磁盘占用
- npm / yarn classic：每个项目的
node_modules是独立副本。同版本的 React 在 10 个项目中将占据 10 份磁盘空间。 - pnpm：所有包统一存储在全局 store，项目内通过硬链接引用。相同文件在磁盘上只有一份。对拥有多个项目或 monorepo 的开发者效果明显。
- yarn PnP：包以 zip 压缩格式存储在
.yarn/cache/，也可跨项目共享，但访问时需要解压。
Lockfile
| 包管理器 | Lockfile | 特点 |
|---|---|---|
| npm | package-lock.json | npm v5 后稳定，JSON 格式较冗长 |
| yarn classic | yarn.lock | 类似 YAML，可读性较好 |
| pnpm | pnpm-lock.yaml | 类似 YAML，记录依赖拓扑 |
| cnpm | 早期无 / 现兼容 npm | 受镜像同步影响 |
lockfile 保证在不同环境安装时得到完全相同的依赖树。cnpm 早期版本缺少 lockfile 支持，会导致开发环境和部署环境的依赖版本不一致，当前版本已修复。
Monorepo 支持
- npm workspaces（v7+）：基本工作区能力，缺少高级过滤和编排。
- yarn workspaces：可配合
yarn workspaces foreach按拓扑顺序执行命令。 - pnpm workspaces：
pnpm --filter语法灵活，例如pnpm --filter "./packages/*" --filter "!packages/docs" run build，并提供pnpm deploy命令生成精简的部署目录。 - cnpm：不支持 workspace。
在 monorepo 中，pnpm 的硬链接机制使多个子包可以共享相同的依赖实体，避免重复安装，结合过滤和部署功能提供完善的工作流。
安全性
- npm：
npm audit内置漏洞扫描。 - yarn：
yarn audit规则与 npm audit 同源。yarn Berry 提供yarn npm audit。 - pnpm：
pnpm audit可用。其严格的依赖拓扑本身降低了供应链攻击面——代码无法访问未声明在package.json中的包。 - cnpm：无内置审计命令。
注意点
- 幽灵依赖 是 npm/yarn flat hoisting 的固有特征。项目在某环境下正常，换用 pnpm 或另一包管理器可能立即报错，说明代码中存在未声明的隐式依赖。
- pnpm 的兼容性：大部分 npm 包可在 pnpm 下正常工作，但部分包利用 hoisting 特性隐式访问依赖，以 pnpm 的严格模式运行时会失败。可临时为这些包使用
public-hoist-pattern配置将其依赖提升，但这会打破严格隔离。 - yarn PnP 生态兼容性仍需验证，某些工具（如部分 IDE 插件、老旧的构建脚本）尚未支持。迁移前应进行充分测试。
- cnpm 的缓存一致性：镜像同步存在延迟，在次新版本发布时可能出现安装到旧版本的情况，需要严格确定性的场景应谨慎使用。
限制
- pnpm 的严格拓扑意味着依赖必须显式声明，迁移现有项目时可能需要补齐缺失的依赖声明。
- yarn PnP 模式在不支持 PnP 的工具或库面前会直接失败，需要在使用前查清兼容性列表。
- cnpm 不自带依赖分析或审计功能，也无法处理 monorepo 场景。
应用
单体应用或小型项目：pnpm 具有较快的安装速度和内置幽灵依赖防护，且 CLI 与 npm 高度兼容，迁移成本低。
monorepo：pnpm 的 workspace、过滤器和硬链接共享依赖机制使其成为当前主流方案。Turborepo、Nx 等工具也推荐搭配 pnpm。
兼容性优先的项目：npm 作为 Node 内置工具，零额外安装，兼容性最好，适合依赖大量老旧包的项目。
已有 yarn classic 的项目：如果团队已有稳定的
yarn.lock和开发习惯，可以继续使用 yarn v1，不必强制迁移。国内网络问题：无需安装 cnpm CLI，直接为 npm 或 pnpm 配置淘宝镜像源即可：
bashnpm config set registry https://registry.npmmirror.com pnpm config set registry https://registry.npmmirror.com