在团队技术方案评审或前端面试中Monorepo 和 pnpm 几乎是一对固定组合。很多候选人能流畅说出“Monorepo 便于代码复用、pnpm 安装速度快、能解决幽灵依赖”但只要面试官追问一句“pnpm 是怎么做到没声明就不能用的”气氛往往会突然安静下来。因为这个问题的答案不在命令里而在 pnpm 的依赖管理原理中。本文就从这个面试追问出发完整梳理 Monorepo 的核心价值、pnpm 与 npm/yarn 的依赖结构差异、幽灵依赖产生的原因与危害并用一个可运行的 pnpm workspace 项目展示“依赖隔离”到底是怎么实现的。最后还会给出 pnpm 实战中常见报错的排查思路和工程规范建议希望能帮你把这块知识补齐。1. Monorepo 为什么流行1.1 从多仓库到单仓库在早期前端工程化中一个大型业务项目往往拆成多个独立 Git 仓库每个仓库维护自己的 package.json、node_modules 和构建配置。这种 MultiRepo多仓库模式的好处是边界清晰、仓库独立发布但坏处也很明显公共代码要抽成 npm 包发到私有源改一行公共代码要经历“改包、发包、升级依赖、重新安装”这条链路各仓库依赖版本漂移后联调时经常出现“本地好好的一起跑就报错”。Monorepo单仓库多包则把多个子项目放在同一个 Git 仓库中管理。比如一个仓库下有packages/shared、packages/web、packages/server三个包它们共享一套依赖锁定文件、一套 CI 配置、一次提交记录。这样公共代码修改后能即时被同仓库的其他包引用不需要先发版尤其适合组件库、工具链、业务中台这类代码耦合较紧密的场景。需要注意的是Monorepo 不只是“把代码放在一个仓库里”它的关键在于配套的依赖管理工具和构建编排能力。如果没有 workspace 支持和依赖隔离单仓库很快就会变成依赖地狱。1.2 Monorepo 的核心收益Monorepo 能成为中大型前端项目的普遍选择主要有四个收益第一是代码复用成本低。公共工具函数、类型定义、UI 组件可以作为 workspace 包被多个子项目直接引用改动即时生效无需发布到 npm 源。第二是依赖统一管理。根目录一份 lockfile 能锁定所有子包的依赖版本避免同一依赖在多个子包中版本不一致。版本冲突排查范围也大幅缩小。第三是原子化提交与联调顺畅。一次提交可以同时包含 API 变更和前端页面改动代码评审时能清楚看到跨包的关联变动。第四是有利于统一规范与 CI 优化。eslint、prettier、tsconfig 这些配置可以收敛到根目录CI 可以只构建发生变更的包节省流水线时间。但 Monorepo 也有代价比如仓库体积增长、权限控制变粗、跨包重构影响面大。所以是否引入 Monorepo要看团队规模和代码耦合程度不能因为追求架构先进而盲目上。1.3 workspace 工具的演进Monorepo 的落地离不开 workspace 能力。npm 在 7.x 之后支持workspaces字段yarn 有yarn workspacespnpm 则通过pnpm-workspace.yaml声明工作区范围。相比之下pnpm 在 Monorepo 场景下更受欢迎不只是因为安装速度快更因为它从设计层面解决了 npm/yarn 遗留的幽灵依赖问题。这也是面试官追问“pnpm 怎么做到没声明就不能用”时真正想听到的内容。2. 幽灵依赖问题是如何产生的2.1 什么是幽灵依赖幽灵依赖Phantom Dependency是指你在代码里引用了一个包但这个包并没有直接声明在项目的dependencies或devDependencies中。代码能跑起来只是因为它恰好被安装在了node_modules的某个可以被解析到的位置。举一个非常常见的例子{ name: demo-app, dependencies: { lodash: ^4.17.21 } }项目依赖里只声明了 lodash。但如果 lodash 内部依赖了一个工具库is-number使用 npm 安装后node_modules/is-number也会存在。此时代码里直接require(is-number)通常能正常执行尽管is-number根本不在你的 package.json 中。这种“没有被声明却能使用”的依赖就是幽灵依赖。它不会立刻报错但会在不经意间埋下隐患。2.2 npm 扁平化 node_modules 的副作用要理解幽灵依赖为什么普遍存在需要先看看 npm 的依赖安装策略。在 npm 3 之前node_modules是嵌套结构的。一个包依赖的包会安装在这个包的node_modules内部目录层级可以很深容易出现“同一个包被安装很多份”和“Windows 路径过长”的问题。npm 3 之后采用扁平化策略安装时会把所有依赖包包括间接依赖尽可能提升到顶层的node_modules下。如果版本冲突冲突的包才嵌套安装到对应依赖包的目录里。扁平化解决了路径过长和大量冗余的问题但也带来一个副作用所有间接依赖都被“提升”到了顶层项目代码可以绕过 package.json 直接引用这些间接依赖。这是幽灵依赖产生的根源。2.3 幽灵依赖的危害幽灵依赖的真正风险不在于“多了一个能用的包”而在于它让项目的依赖关系变得不可信。当包管理器从 npm 切换到 pnpm或某个间接依赖升级后不再为你提供这个包项目就会突然出现Cannot find module xxx。这种错误极难排查因为你在 package.json 里根本找不到这个依赖搜索全项目也未必能定位到是谁引入了它。更隐蔽的是如果某个间接依赖发生了破坏性升级你的代码可能在“完全没有改动”的情况下行为异常。因为你根本没声明它也就没有锁定它的版本。从工程规范角度看幽灵依赖还会污染全局类型空间。比如types/is-number被提升到顶层后即使你卸载了项目里的某些代码TypeScript 的类型推断仍可能受到残留类型声明的影响。3. pnpm 的依赖隔离原理3.1 pnpm 的整体思路不做扁平化pnpm 解决幽灵依赖的思路并不是在 npm 扁平化之上做补丁而是彻底改变依赖在磁盘上的组织方式。pnpm 安装依赖后项目的node_modules中只会出现当前 package.json 中直接声明过的依赖并且这些依赖不是真实文件而是指向全局存储的符号链接。真实文件放在磁盘上一个统一的全局存储目录中按内容寻址。这个结构和 npm/yarn 有本质区别。npm 和 yarn 的node_modules是实际文件的目录树pnpm 的node_modules更像一张“依赖索引表”只暴露该项目应当可见的包。3.2 符号链接 硬链接的组合pnpm 的高效和隔离依赖两个底层机制符号链接symlink和硬链接hard link。当执行pnpm install时pnpm 会做这几件事将所有依赖包的解压内容缓存到全局 store 中store 中的文件按内容哈希命名相同的文件只存一份。在项目的node_modules/.pnpm/nameversion/node_modules/name位置为每个包创建指向全局 store 的硬链接。在项目顶层node_modules/name位置为直接依赖创建指向.pnpm目录中对应包的符号链接。硬链接确保了同一个包在不同项目中不会重复占用磁盘空间符号链接则控制了依赖的可见性。但这里有一个关键点.pnpm目录中的每个包其node_modules下只包含该包真正声明的依赖。pnpm 会读取每个依赖包的 package.json再为它的每个依赖创建符号链接而不是简单地把所有东西平铺开。3.3 为什么“没声明就不能用”现在可以正面回答面试官的问题了。pnpm 的node_modules目录结构大致如下node_modules/ ├── .pnpm/ │ ├── lodash4.17.21/ │ │ └── node_modules/ │ │ └── lodash/ │ ├── is-number7.0.0/ │ │ └── node_modules/ │ │ └── is-number/ │ └── demo-app1.0.0/ │ └── node_modules/ │ └── demo-app/ ├── lodash - .pnpm/lodash4.17.21/node_modules/lodash └── .modules.yaml顶层node_modules里只有lodash这个直接依赖的符号链接。虽然.pnpm/lodash4.17.21/node_modules内部也有is-number的链接但它位于lodash包的私有目录中。Node.js 解析require(is-number)时会从当前文件所在目录逐级向上查找node_modules。在你的项目源码中require会先查项目的node_modules找不到就继续向上级目录查找但不会进入node_modules/.pnpm/lodash4.17.21/node_modules这种嵌套路径。因此未在 package.json 中声明的is-number对项目源码不可见会直接抛出MODULE_NOT_FOUND。这就是“没声明就不能用”的底层实现不是靠代码层面的拦截而是利用文件系统结构从依赖解析的起点就切断了访问路径。4. 从零搭建 pnpm Monorepo 工程理解了原理后我们用一个小项目实际体验一遍。下面会创建一个包含两个子包的 pnpm workspace 工程并演示依赖隔离效果。4.1 前置环境准备本文示例在 Windows 11 Node.js 环境下运行macOS/Linux 命令基本一致。你需要先确认本机已安装 Node.js然后通过 npm 安装 pnpmnpm install -g pnpm安装完成后验证版本pnpm --version如果你的电脑提示“pnpm 不是内部或外部命令”通常是全局 bin 目录没有加入系统 PATH后文常见问题部分会给出完整解决方案。4.2 初始化 Monorepo 根目录创建项目文件夹并在根目录初始化mkdir pnpm-monorepo-demo cd pnpm-monorepo-demo pnpm init根目录生成的package.json需要做一点修改删除 name、version 以外的私有字段并声明这是私有仓库不允许直接发布{ name: pnpm-monorepo-demo, version: 1.0.0, private: true, scripts: { dev: pnpm -r --parallel dev } }然后在根目录创建pnpm-workspace.yaml声明工作区包含的包目录packages: - packages/*注意pnpm-workspace.yaml是 pnpm 识别 Monorepo 工作区的核心文件。没有它pnpm 就不会把子包作为 workspace 包处理。4.3 创建 workspace 子包在packages目录下创建两个子包第一个是packages/shared用来放公共工具函数{ name: demo/shared, version: 1.0.0, main: src/index.js, scripts: {}, dependencies: {} }创建packages/shared/src/index.js// 文件路径packages/shared/src/index.js function formatName(name) { return Hello, ${name}!; } module.exports { formatName, };第二个是packages/app作为业务应用依赖demo/shared{ name: demo/app, version: 1.0.0, main: src/index.js, scripts: { dev: node src/index.js }, dependencies: { demo/shared: workspace:*, lodash: ^4.17.21 } }创建packages/app/src/index.js// 文件路径packages/app/src/index.js const { formatName } require(demo/shared); const _ require(lodash); console.log(formatName(Monorepo)); console.log(_.join([pnpm, workspace, demo], -));这里用workspace:*声明对demo/shared的依赖。这是 pnpm workspace 的协议语法表示这个依赖来自当前工作区而不是 npm 源且不需要指定具体版本。安装时 pnpm 会自动把demo/shared链接到当前 workspace 中对应包。4.4 安装依赖并运行在根目录执行安装命令pnpm install执行完以后观察根目录node_modulesnode_modules/ └── .pnpm/你会发现根目录node_modules中并没有lodash的符号链接因为只有packages/app声明了lodash。再进入子包目录执行运行脚本pnpm dev预期输出Hello, Monorepo! pnpm-workspace-demo这说明 workspace 包demo/shared已经被正确链接应用可以正常引用。4.5 验证依赖隔离效果现在来做一个实验。在packages/app/src/index.js中故意引用一个没有声明的间接依赖。lodash 内部依赖的包并不固定这里可以随意尝试一个不存在的依赖名// 文件路径packages/app/src/index.js const { formatName } require(demo/shared); // 故意引用未声明的包验证 pnpm 隔离 try { require(some-phantom-dependency); console.log(幽灵依赖存在); } catch (error) { console.log(找不到模块, error.code); }如果使用 npm 安装some-phantom-dependency大概率会因为被提升到顶层node_modules而能被加载取决于 lodash 是否实际依赖它而在 pnpm 中由于项目顶层node_modules只包含demo/shared代码会直接捕获到MODULE_NOT_FOUND错误。这个实验直观地说明了 pnpm 的隔离原理依赖解析只能命中项目声明过的包未被声明的包即使存在于.pnpm内部也对项目源码不可见。4.6 查看真实目录结构如果你还想进一步观察符号链接可以在packages/app目录执行ls -la node_modules在 Linux/macOS 上可以看到类似输出node_modules/ ├── .bin ├── demo - ../../shared └── lodash - .pnpm/lodash4.17.21/node_modules/lodashWindows 下可以用命令查看但输出格式略有不同。这里的重点在于顶层只有两个直接依赖的链接demo/shared指向同级目录lodash指向.pnpm内部路径不再有整棵文件树的扁平展开。5. pnpm 与 npm、yarn 的核心对比很多人在技术选型时纠结 pnpm 和 npm/yarn 的区别这里整理几个关键维度。对比维度npm/yarn 扁平化pnpmnode_modules 结构尽量把依赖平铺到顶层只暴露直接依赖的符号链接间接依赖可见性可见项目代码可越级引用不可见访问会报错磁盘占用多项目重复安装占空间大全局 store 硬链接重复文件只存一份安装速度受依赖数量和网络影响有缓存时安装速度更快安全性无法防止依赖被误用依赖边界更清晰但 pnpm 并非没有缺点。它的符号链接和 Node.js 生态中部分工具存在兼容性问题比如某些工具在解析真实路径时可能拿到 store 中的路径而不是项目相对路径。另外pnpm 对 peerDependencies 的处理比较严格如果项目中有大量不规范依赖升级到 pnpm 时会遇到一些需要手动处理的报错。对于新项目我倾向于直接选择 pnpm workspace对于存量 npm 项目迁移前需要先评估依赖的规范性尤其是是否存在大量未声明的间接依赖。6. 常见问题与排查思路6.1 pnpm 不是内部或外部命令在 Windows 上安装 pnpm 后执行pnpm --version报错pnpm : 无法将“pnpm”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。原因通常是 npm 全局安装目录没有加入系统 PATH。解决办法有两种第一种是先查看 npm 全局前缀npm config get prefix然后把输出的路径例如C:\Users\你的用户名\AppData\Roaming\npm加入系统环境变量 PATH。第二种是使用 Corepack 启用corepack enable corepack prepare pnpmlatest --activateCorepack 是 Node.js 官方提供的包管理器管理工具启用后能直接用pnpm命令。6.2 Node.js 版本不满足要求执行 pnpm 命令时可能出现error: this version of pnpm requires at least node.js v22.13 the current version is v18.x.x这说明当前 Node.js 版本低于 pnpm 要求的最低版本。pnpm 的新版本通常会跟进 Node.js 的最新 LTS。解决方法是使用 nvm、fnm 或 nvm-windows 切换到更高版本的 Node.js或者安装与当前 Node 版本兼容的旧版 pnpmnpm install -g pnpm86.3 安装依赖或下载缓慢在某些网络环境下pnpm install会长时间卡在下载阶段。常见解决方案是配置国内镜像源pnpm config set registry https://registry.npmmirror.com如果需要恢复官方源pnpm config set registry https://registry.npmjs.org6.4 幽灵依赖导致代码迁移报错从 npm 迁移到 pnpm 后项目中出现大量Cannot find module xxx几乎可以断定是幽灵依赖造成的。排查思路如下先确认报错包是否在 package.json 中声明。如果没声明找到它是被哪个直接依赖间接引入的通过pnpm why 包名命令查看依赖链路pnpm why is-number然后再决定是把该依赖显式声明到 package.json还是调整代码消除对间接依赖的引用。6.5 子包之间互相依赖时版本没有实时更新Monorepo 中子包 A 修改代码后子包 B 引用时没有生效。这是因为 pnpm 的workspace:*链接指向的是 A 包的入口文件。如果 A 包发布到 npm 前需要执行构建而 B 引用的是 A 的构建产物就需要先构建 A。最简单的方案是使用main: src/index.js直接指向源码或者在脚本中先执行依赖包的 build。6.6 安全提示不要随意删除全局 storepnpm 的全局 store 中保存着所有项目的依赖文件。如果手动删除 store可能导致其他项目损坏。正确做法是使用 pnpm 自带的清理命令pnpm store prune该命令会清理 store 中未被任何项目引用的孤儿文件。问题现象常见原因解决思路pnpm 不是内部或外部命令npm 全局目录未加入 PATH配置环境变量或使用 Corepack版本不满足要求本地 Node.js 版本过低升级 Node.js 或降级 pnpm下载慢registry 访问受限配置 npmmirror 镜像Cannot find module幽灵依赖被隔离使用 pnpm why 找到上游声明workspace 子包不更新引用的是构建产物指向源码或先构建依赖包7. 最佳实践与工程建议7.1 workspace 包划分原则在 Monorepo 中子包不是越多越好。推荐的划分方式是只把真正会被多个上层项目复用的代码抽成 workspace 包例如业务组件库、API 类型定义、通用工具函数、公共配置。单纯属于单个业务的页面和逻辑应该留在各自的应用包内避免过度拆分增加心智负担。7.2 所有依赖必须声明这是 pnpm 模式下必须遵守的纪律。不要在代码里依赖“恰好存在”的间接依赖。如果发现代码使用了某个包但它没有出现在 package.json 中立刻补上显式声明。这个习惯能避免项目在包管理器切换或依赖升级时突然崩溃。7.3 统一配置与脚本根目录的package.json可以集中管理跨子包的公共命令。例如{ scripts: { build: pnpm -r --filter./packages/* build, lint: pnpm -r lint, test: pnpm -r test } }-r表示递归执行所有子包--filter可以精确指定执行范围。CI 流水线中建议按需构建不要每次全量构建。7.4 谨慎控制根目录依赖根目录的devDependencies通常只放构建、代码规范、测试相关的工具链比如typescript、eslint、prettier、vitest。业务运行时依赖应放在对应子包中。这样能让依赖边界更清晰也方便子包独立发布。7.5 构建脚本的安全问题pnpm 10 开始对依赖包的生命周期脚本加强了安全检查。安装某些依赖时终端会出现Ignored build scripts: esbuild. Run pnpm approve-builds to pick which dependencies should be allowed to run.这是 pnpm 的安全策略默认不执行依赖包中可能包含任意命令的install脚本需要开发者手动确认。对于你信任的依赖执行pnpm approve-builds按提示勾选允许的包。对于不熟悉的依赖建议先检查其 package.json 中的 install 脚本内容确认无风险后再允许执行。这个机制能有效防止依赖供应链攻击。7.6 版本锁定与升级策略Monorepo 的根目录会生成pnpm-lock.yaml该文件必须提交到 Git 仓库。新增或升级依赖后锁定文件会随之更新。升级依赖时建议使用pnpm update会按照锁定文件的版本范围批量更新避免手动改动造成不一致。7.7 与 CI/CD 结合的注意点在 CI 环境中开启 store 缓存能显著加快安装速度。可以在缓存目录中保留~/.pnpm-storemacOS/Linux或对应 Windows 目录并在每次 CI 运行前恢复缓存。配置side-effects-cache等构建缓存时要注意 pnpm 的符号链接结构可能让部分缓存工具误判文件内容实际项目中需要验证缓存正确性。8. 回到面试问题本身回到最开始的问题。候选人能说出“代码复用、速度快、依赖隔离”属于扫盲级答案而能解释清楚“没声明就不能用”则体现对包管理器底层结构的理解。面试官想要听到的完整链路大概是这样的Monorepo 解决的是多项目代码复用和统一依赖的问题。pnpm 实现依赖隔离的核心是改变了node_modules的物理结构所有依赖的真实文件存储在全局 store 中项目内只保留符号链接.pnpm目录为每个包构造独立的虚拟 node_modules仅暴露该包声明的依赖。Node.js 的模块解析机制沿目录向上查找而符号链接又严格控制了查找范围最终实现“未声明依赖不可访问”的效果。这里还需要补充一个容易混淆的点符号链接指向.pnpm内部包目录后Node.js 解析这个包自己的依赖时会从.pnpm/nameversion/node_modules/开始查找。因为该目录下只有这个包声明过的依赖链接所以它既不会访问到项目顶层也不会误入其他包的私有目录。这种“链接里的链接”设计才是 pnpm 隔离的完整面貌。当你把这层机制理解清楚后再去回答“pnpm 的优势”“Monorepo 为什么用 pnpm”“幽灵依赖如何解决”这类问题就不只是背答案而是可以结合实际项目场景讲清楚设计取舍和潜在风险。这也是本文最希望帮你建立的能力。如果接下来要深入学习建议按这个顺序继续先自己搭建一个包含三四个子包的 pnpm workspace 项目手工查看各层 node_modules 的链接关系然后尝试把现有的 npm 项目迁移到 pnpm记录所有报错并归类最后阅读 pnpm 官方文档中关于 store 架构和 dependency resolution 的章节形成更完整的知识地图。