npm/Yarn Classic 的 node_modules 像座山,装 Next.js 项目 600MB 起,跨项目重复存十份。pnpm 用内容寻址仓库 + 硬链接 + 符号链接把全世界的依赖只存一份,每个项目只放软链,磁盘从 600MB 降到 200MB,装包速度还快 2-3 倍。本教程 10 章,从核心原理到 monorepo catalog、patch、CI 缓存全覆盖。
npm/Yarn 时代的 node_modules 痛点,pnpm 用架构创新一次解决
npm 为了解决依赖冲突发明了"扁平化 node_modules",把所有包平铺到顶层。代价是:幽灵依赖(没在 package.json 里却能 import)、磁盘爆炸(每个项目重复存 600MB)、装包慢(每次都要复制文件)、跨包污染(A 装了 lodash,B 也能用)。这些问题在 monorepo 和 CI 场景被放大十倍。
pnpm 的解法是全局内容寻址仓库 + 硬链接 + 符号链接的严格布局:全世界依赖只存一份在 ~/.local/share/pnpm/store,项目 node_modules 用硬链接指过去;.pnpm/ 目录真实扁平,外层用软链构造出"只看得到 package.json 里声明的依赖"的假象——幽灵依赖被彻底堵死。再加上 workspaces、catalog(pnpm 9 杀手特性)、patch、filter,pnpm 已是 2026 年 JS monorepo 的事实标准。
10 章 · 从原理到 monorepo 与 CI 实战
pnpm init、lockfile v9、pnpm install 背后发生了什么。
Chapter 03
Content-Addressable Store
~/.local/share/pnpm/store、哈希索引、跨项目复用、CI 加速 store mount。
Chapter 04
严格的 node_modules 布局
node_modules/.pnpm/ 真实扁平、外层虚拟、为什么幽灵依赖被堵死。
Chapter 05
Workspaces:单仓多包
pnpm-workspace.yaml、workspace:* 协议、包间引用、一次 install 全装。
Chapter 06
Filter:只对一部分包操作
-F/--filter、路径过滤、依赖图过滤、.../^.../{...} 语法。
Chapter 07
Catalog:版本对齐利器
catalog: 协议把版本集中,升级一处全仓同步。pnpm 9 的杀手特性。
Chapter 08
Patch:改第三方包不 fork
pnpm patch / patch-commit、patchedDependencies、补丁生命周期。
Chapter 09
CI / Docker 最佳实践
--frozen-lockfile、store-dir 缓存、Turborepo/Nx 组合、Docker 多阶段。
Chapter 10
脚本 · publish · 常见坑
生命周期钩子、pnpm publish workspace 版本策略、迁移 npm/Yarn 避坑。