Monorepo 和 pnpm 是一对经常同时出现的技术词也是一道前端和 Node.js 工程化面试题的常见组合。Monorepo 负责把多个项目从多个仓库收敛到一个仓库解决代码复用和跨包变更协同的问题pnpm 负责在这些项目之间安装依赖保证每个包的依赖关系足够严格。真正拉开候选人差距的是“幽灵依赖”这个问题。很多人能说出 pnpm 比 npm 快、能隔离依赖但面试官继续问一句“pnpm 怎么做到没声明就不能用”如果答不清楚符号链接和 node_modules 的布局前面说的优势就会像在背概念。这篇文章会把 Monorepo、pnpm、幽灵依赖这条链路完整拆开从原理到实操再到常见报错排查和面试表达。1. Monorepo 要解决的不是“少建几个仓库”这么简单1.1 从多仓库到单体仓库核心是“变更协同”在很多中型团队里一开始每个业务模块独立建仓库。这样做的好处是团队边界清晰、权限可控但缺点会在共享代码时暴露出来。假设有三个项目管理后台、用户端、公共组件库。公共组件库单独发布到 npm管理后台和用户端通过安装组件库版本来使用。当管理后台发现组件库某个 API 需要调整时必须先改组件库、发布新版本再回到管理后台升级依赖。如果组件库同时被用户端依赖还要考虑用户端是否也愿意一起升级。一次跨模块改造变成了多次跨仓库发布协作。Monorepo 把多个项目放在同一个仓库里共享代码不再需要先发布到远程 registry。通过 workspace 机制一个包可以直接引用另一个包的源码本地修改后立即可见。对 monorepo 来说“代码复用”不再靠 npm 包版本号驱动而是靠源码级别的工作区依赖驱动。Monorepo 带来的更关键收益是跨包变更的原子性。把公共包和相关业务包放在同一个提交里改动、测试、构建、发布可以一起完成不存在“组件库发布了但业务还没更新”的中间状态。1.2 依赖组织方式才是 Monorepo 的隐藏难点但 Monorepo 不是“把代码放在一起就结束”。真正难的是依赖管理。一个仓库里往往有十几个 package有些包是自己的业务代码有些包是共享的 lint 配置、脚本工具、公共类型定义。每个包既希望复用公共配置又希望业务依赖关系保持清晰。如果所有依赖都被安装到根目录安装速度快但会出现一个非常现实的问题某个业务包可以访问它根本没有声明过的第三方依赖。这样的代码在当前环境能跑换一个依赖提升规则不同的环境可能立刻报错。所以在 Monorepo 里包管理器不只是“下载依赖”的工具它实际上决定了每个包能看见哪些依赖、看不见哪些依赖。npm 和 Yarn classic 使用的提升策略相对宽松pnpm 使用的非提升布局相对严格。“Monorepo pnpm” 之所以常见不是因为 pnpm 拉取依赖更快而是因为它从安装结构上保证了依赖隔离。1.3 为什么 pnpm 适合 Monorepopnpm 有四个能力对 Monorepo 很有价值第一内容寻址存储。相同版本的包只在全局 store 中保存一份项目里的node_modules通过硬链接或符号链接引用跨项目共享文件磁盘占用远小于 npm。第二严格的依赖布局。每个包只能看到自己package.json里直接声明的依赖不会因为依赖提升而意外访问到其他包的传递依赖。第三workspace 协议。可以在pnpm-workspace.yaml中声明工作区内部包之间的依赖使用workspace:*协议安装时自动关联本仓库内的包。第四统一锁文件。整个 monorepo 只需要一份pnpm-lock.yaml多包共用的依赖版本更一致升级依赖时更容易判断影响范围。下面的表格把 Monorepo 和多仓库的关键差异列出来便于快速理解。维度多仓库Monorepo代码复用发布 npm 包后安装workspace 源码级引用跨包改动多次发布、多次升级一次提交原子变更依赖版本各项目独立锁文件统一锁文件构建隔离天然隔离需要依赖管理体系保障权限控制仓库级别清晰依赖 CODEOWNERS 等规则协作成本跨仓库沟通成本高同仓库协作成本低2. 幽灵依赖到底指的是什么2.1 Node 模块解析逻辑决定了“能看见什么 npm 就装什么”在解释幽灵依赖之前先看 Node 的模块解析逻辑。当代码执行require(some-package)时Node 会从当前文件所在目录开始依次往上级目录查找node_modules。也就是说packages/app-a/src/index.js引用某个依赖时Node 会查找packages/app-a/src/node_modulespackages/app-a/node_modulespackages/node_modulesnode_modules如果一直找不到就报Cannot find module。Node 本身不会校验这个包是否写在package.json的dependencies里。它只看文件系统里有没有。因此真正决定“能不能用”的是包管理器把依赖放在哪里。这就是为什么依赖布局会直接影响代码可移植性和工程质量。2.2 npm 的提升策略让传递依赖“跑”到了顶层npm 早期版本的依赖结构是嵌套的。项目安装 AA 依赖 BB 依赖 Cnode_modules会一层层嵌套下去。这样做的问题很明显同一个 C 如果被多个包依赖会被安装多份磁盘浪费严重。npm 从 v3 开始使用“依赖提升”策略安装时尽量把依赖包的传递依赖提升到顶层node_modules。如果一个项目声明了 AA 又声明了 B安装后顶层node_modules里不仅会有 A还会有 B。这个策略解决了磁盘浪费问题却引入了新问题。项目代码里虽然没有声明 B但因为 B 被提升到了顶层require(b)仍然可以解析成功。这个“没有被声明却能被使用”的依赖就是幽灵依赖。例如{ name: my-project, version: 1.0.0, dependencies: { package-a: ^1.0.0 } }假设package-a依赖package-b。安装后即使package.json中没有package-b代码里也可能可以require(package-b)。在 npm 的默认提升策略下这种代码常常能跑通。2.3 幽灵依赖为什么危险幽灵依赖最大的问题是它把“可运行”和“正确声明”拆开了。第一是版本漂移。项目没有直接声明 BB 的版本由 A 的依赖范围决定。A 升级后B 可能从 1.0 升到 2.0项目里那些“碰巧能用”的 B 相关代码可能在没有任何变更的情况下崩掉。第二是迁移困难。项目从 npm 迁移到 pnpm 时pnpm 默认不再提升传递依赖。原本能解析的require(b)会直接报Cannot find module b改造需要把所有隐式依赖逐个声明到package.json。第三是工具无法校验。像eslint-plugin-import的规则、depcheck这类依赖检查工具本质上是根据package.json分析代码引用的依赖。如果代码大量使用未声明依赖这些工具就会报出一堆“虚假”的未安装依赖或者无法准确判断问题。下表是三种依赖使用状态的区别。状态package.json 声明代码运行结果风险正常依赖已声明可用低幽灵依赖未声明当前环境可用高版本不可控缺失依赖未声明报 Cannot find module可及时发现3. pnpm 用“符号链接加内容寻址存储”实现依赖隔离3.1 非提升布局所有依赖都收进 .pnpm 目录pnpm 的核心思路是不要让依赖“自动跑”到顶层node_modules而是把所有实际安装的依赖放在一个名为.pnpm的目录下按“包名加版本号”组织。假设项目依赖debugdebug又依赖ms。pnpm 安装后的简化结构如下node_modules ├── .pnpm │ ├── debug4.3.4 │ │ └── node_modules │ │ ├── debug │ │ └── ms - ../../ms2.1.3/node_modules/ms │ └── ms2.1.3 │ └── node_modules │ └── ms └── debug - .pnpm/debug4.3.4/node_modules/debug根目录node_modules下只出现项目直接声明的依赖这里只有debug的符号链接。ms是debug的依赖它被放在.pnpm/debug4.3.4/node_modules/ms并且只对debug可见。3.2 符号链接如何让“没声明就不能用”成立符号链接在这个机制里承担了两个职责。第一个职责是“暴露直接依赖”。项目在package.json里声明了debugpnpm 就会在项目根node_modules下创建一个指向.pnpm/debug4.3.4/node_modules/debug的符号链接。代码require(debug)沿着 Node 解析规则找到这个符号链接成功进入包目录。第二个职责是“在包内部提供自己的依赖”。debug包运行时会需要mspnpm 在.pnpm/debug4.3.4/node_modules下创建ms的符号链接让debug在自己作用域内能找到ms。因为传递依赖没有提升到根目录项目的顶层node_modules里只有直接声明的依赖。当代码试图require(ms)而package.json没有声明ms时模块解析会一路从当前目录向上查找最终发现不存在直接报错。所以“没声明就不能用”不是一种运行时拦截而是文件系统布局带来的必然结果。这个回答在面试里比较接近面试官想听的底层机制。注意pnpm 默认不是对全体依赖都做软链接而是对“每个依赖的可见范围”做软链接。它保证的是“项目的直接依赖只暴露给你声明过的包”而不是“所有依赖只能被唯一一个包使用”。3.3 内容寻址存储与硬链接的优势pnpm 在安装依赖时会先把包文件下载到全局 store 中。store 是内容寻址的也就是说同一个包同一版本只需保存一份文件。项目安装时pnpm 通过硬链接把包文件映射到node_modules/.pnpm。硬链接的好处有两个磁盘复用。多个项目同时依赖同一个版本的同一包时不会重复下载和存储。安装速度快。本地 store 已存在时pnpm install不需要再次下载只需要创建链接。查看全局 store 路径可以使用pnpm store path硬链接不是完全没有限制。硬链接要求源文件和目标文件处于同一个磁盘分区。如果全局 store 和项目不在同一个盘pnpm 可能退化为复制文件。此时磁盘节省效果会下降但仍然保留依赖隔离能力。3.4 npm、Yarn classic、pnpm 的依赖布局对比维度npm / Yarn classicpnpm顶层 node_modules提升大量传递依赖只放直接依赖的符号链接幽灵依赖容易产生默认避免磁盘占用每个项目独立复制全局 store 复用安装速度依赖数量越多越慢已缓存依赖用链接完成依赖隔离弱强workspace 支持npm v7 / Yarn workspacepnpm-workspace.yaml4. 在 Monorepo 中安装 pnpm 并建立最小项目4.1 环境准备与安装方式先确认 Node 版本因为 pnpm 对 Node 版本有要求。新版本 pnpm 可能需要较新的 Node旧 Node 环境会直接报错error: this version of pnpm requires at least node.js v22.13查看当前环境node -v npm -v如果项目里有.nvmrc优先使用.nvmrc中的版本没有则建议使用当前 Node 的 LTS 版本。安装 pnpm常见方式有两种npm install -g pnpm或者使用 Node 自带的 Corepackcorepack enable corepack prepare pnpmlatest --activate安装完成后验证pnpm -v如果提示“pnpm 不是内部或外部命令”说明全局安装目录没有加入 PATH排查方法在第 6 章会详细说明。4.2 配置镜像以加快依赖下载默认 pnpm 会访问官方 npm registry。在大陆网络环境下下载慢或超时很常见。可以设置国内镜像pnpm config set registry https://registry.npmmirror.com推荐在项目根目录创建.npmrc把配置固化到项目里registryhttps://registry.npmmirror.com network-timeout600000 fetch-retries5network-timeout的单位是毫秒600000表示 10 分钟。如果网络较差可以继续调大。.npmrc中的配置会随项目一起提交团队成员安装时行为一致。4.3 最小 Monorepo 项目结构这里创建一个包含三个包的最小 Monorepodemo/shared公共工具包。demo/app-a业务包 A依赖shared。demo/app-b业务包 B也依赖shared。目录结构如下monorepo-demo ├── packages │ ├── app-a │ │ ├── index.js │ │ └── package.json │ ├── app-b │ │ ├── index.js │ │ └── package.json │ └── shared │ ├── index.js │ └── package.json ├── .npmrc ├── package.json └── pnpm-workspace.yaml在pnpm-workspace.yaml中声明工作区packages: - packages/*根目录package.json设置为私有项目并把构建脚本指向所有子包{ name: monorepo-demo, private: true, scripts: { build: pnpm -r run build } }shared包的内容{ name: demo/shared, version: 1.0.0, main: index.js, exports: ./index.js }// packages/shared/index.js function add(a, b) { return a b; } module.exports { add };app-a的依赖声明{ name: demo/app-a, version: 1.0.0, scripts: { build: node index.js }, dependencies: { demo/shared: workspace:* } }// packages/app-a/index.js const { add } require(demo/shared); console.log(add(1, 2));app-b的 package.json 与此类似可以把输出内容改成不同文字便于观察。4.4 安装依赖与运行验证在根目录执行pnpm install执行后根目录会出现pnpm-lock.yamlnode_modules下会出现工作区包符号链接。此时验证所有包的构建脚本pnpm -r run build也可以单独运行某个包pnpm --filter demo/app-a run build--filter是 pnpm 在 Monorepo 里最常用的选项它有两种常见写法# 只执行当前包 pnpm --filter demo/app-a run build # 执行当前包及其依赖 pnpm --filter demo/app-a... run builddemo/app-a...后面的三个点表示“包含依赖它的链路上的包”。这在发布和构建时非常有用。4.5 workspace 协议的意义workspace:*告诉 pnpm这个依赖不要从远程 registry 找直接在本地工作区里找同名包。它的好处是本地开发时不需要发布demo/shared改完源码业务包立即生效。如果未来需要发布demo/app-a发布时 pnpm 可以把workspace:*转换成具体的版本号也可以选择保留workspace:协议取决于仓库发布策略。5. 运行时验证未声明的依赖为什么找不到5.1 构造一个能暴露幽灵依赖的示例用一个更贴近实际问题的例子来验证 pnpm 的严格模式。在 Monorepo 中增加一个名为demo/lib-b的包它声明依赖debug{ name: demo/lib-b, version: 1.0.0, main: index.js, dependencies: { debug: ^4.3.4 } }现在让demo/app-a不声明debug只看它的作用域里有没有pnpm install node packages/app-a/index.js如果app-a的代码里尝试加载一个未声明的传递依赖例如// packages/app-a/index.js const debug require(debug); console.log(debug);执行后会出现类似下面的报错Error: Cannot find module debug原因就是 pnpm 没有把debug提升到根目录app-a的node_modules里没有debugNode 向上解析也找不到。5.2 显式声明依赖后验证成功把debug加到app-a的package.json{ name: demo/app-a, version: 1.0.0, scripts: { build: node index.js }, dependencies: { demo/shared: workspace:*, debug: ^4.3.4 } }然后重新安装pnpm install node packages/app-a/index.js这次代码可以正常运行并且能看到debug函数输出。这个前后对比就是“没声明就不能用”最直观的验证。5.3 用 pnpm why 定位依赖来源当项目里出现一个没有直接声明却能访问的依赖时可以用pnpm why排查它来自哪里pnpm why debug输出会显示debug是被谁依赖的、处于哪条依赖链路上。也可以查看某个包的依赖树pnpm list --filter demo/lib-b --depth 1这个命令的作用是回答某一个包到底声明了哪些依赖又实际安装了哪些依赖。排查幽灵依赖时重点看pnpm list输出中的“直接依赖”和“传递依赖”边界。6. 常见安装与使用问题排查6.1 pnpm 不是内部或外部命令在 Windows 上最典型的错误是pnpm : 无法将“pnpm”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。或者pnpm 不是内部或外部命令,也不是可运行的程序或批处理文件。这表示 pnpm 的全局 bin 目录没有被加入到PATH环境变量。先查看 npm 的全局目录npm config get prefix如果是 Windows 并通过 npm 安装路径通常是C:\Users\你的用户名\AppData\Roaming\npm把该路径加入系统环境变量Path保存后重新打开终端。如果能找到pnpm.cmd但终端仍不识别检查是否在修改PATH后没有重新启动终端。注意使用 nvm 切换 Node 版本时全局包会跟着切换。如果安装了多个 Node 版本务必确认当前npm prefix对应的是哪一个 Node 版本。6.2 Node 版本过低导致 pnpm 无法运行报错信息类似error: this version of pnpm requires at least node.js v22.13 the current version is v18.20.0这是 pnpm 版本与 Node 版本不匹配。处理方式有两种升级 Node 到 pnpm 要求的版本。如果项目环境暂时不能升级 Node可以安装一个兼容当前 Node 版本的旧版 pnpm。推荐使用 nvm-windows 或 fnm 管理 Node 版本。仓库根目录可以增加.nvmrc22.13.0然后在 package.json 里用packageManager字段锁定 pnpm 版本{ packageManager: pnpm实际版本 }packageManager字段需要填真实版本号最好和本地安装的 pnpm 保持一致避免 CI 和本地行为不一致。6.3 下载失败或 install 等待时间过长这类问题通常有三个原因。第一个是网络问题。官方 registry 在大陆访问不稳定解决方案是在.npmrc中配置国内镜像registryhttps://registry.npmmirror.com第二个是超时设置过短。当项目依赖很多时单纯靠默认超时可能不够可以加大network-timeoutnetwork
