1. 先从 Monorepo 依赖管理的困扰说起
搞 Monorepo 这些年，我经常被同事问到一个看起来很基础的问题：“我的子包到底该怎么装依赖？”很多人一开始都会觉得，子包不就是目录里的小项目吗，直接cd packages/xxx && npm install不就行了？真这么干了，很快就会碰到版本冲突、依赖重复、node_modules 大爆炸、子包之间互相引用却找不到模块这些诡异现象。
这背后的原因不复杂：Monorepo 并不是“几个独立小项目硬拼在一起”，它是一个整体工作区（workspace），依赖管理必须放在整个仓库的维度去处理。只盯着某个子包单独安装依赖，本质上是把一个整体系统拆成碎片去修，问题只会越修越多。
这篇文章我会用实际工作里最常遇到的操作场景，把子包安装依赖的原理、命令、坑和排查思路一次性讲清楚。内容以目前社区使用率最高的 pnpm、npm、yarn workspace 为主，适合正在搭 Monorepo 或者已经被依赖问题折磨过的人。
1.1 为什么子包依赖会成为问题
先说个我自己的经历。早年在公司内部推行 Monorepo 时，有个后端的同事把项目从原来的多仓库合并到单仓库，然后每个子包都保留了各自的node_modules和package-lock.json。结果每次跑构建，耗时直接从 5 分钟涨到 20 分钟，各种“模块版本对不上”的报错轮番轰炸。
这类问题看起来很随机，但根子是同一个：多个子包共用一套源码树，却按“每个包独立安装依赖”的逻辑去执行，导致依赖树完全失控。
在 Monorepo 里，子包之间的关系通常有三种：A 包依赖外部第三方库，比如 lodash；B 包依赖仓库内的另一个子包，比如packages/utils；C 包既依赖第三方库，也依赖仓库内的多个子包。如果不使用工作区统一管理，第二种关系根本没办法优雅地处理。你只能在 package.json 里写"file:../utils"这种本地路径，或者干脆用 npm link 手动软链，一旦子包变多，维护成本直接起飞。
所以，正确的做法是把整仓库当作一个依赖解析单元，让包管理器统一处理所有子包的依赖关系。这也是后面所有操作的大前提。
1.2 三种主流包管理器的 Monorepo 支持差异
npm、yarn、pnpm 现在都支持 workspace，但实现方式区别很大。我用一个表格把核心差异列出来：
| 特性 | npm workspace | yarn (berry) workspace | pnpm workspace |
|---|---|---|---|
| 依赖安装命令 | npm install -w | yarn workspace | pnpm add --filter |
| 是否支持 workspace 协议 | 不支持workspace:* | 支持 | 支持 |
| 默认依赖提升策略 | 提升到根 node_modules | 提升到根 node_modules | 默认不提升，使用符号链接 |
| 幽灵依赖风险 | 高 | 高 | 低 |
| 磁盘占用 | 高，多次安装可能重复下载 | 同 npm，但 berry 有改进 | 低，全局 store 复用 |
| 锁文件 | 单一 package-lock.json | 单一 yarn.lock | 单一 pnpm-lock.yaml |
看到这个表你就明白了，pnpm 在设计上就是冲着解决依赖隔离和重复安装去的。npm 和 yarn 都能跑 Monorepo，但如果你要求严格、团队成员多，我基本都会建议用 pnpm。下面所有实操我会以 pnpm 为主，npm 和 yarn 的对应写法也会给出来。
2. 子包安装依赖的核心机制
说实话，命令只是表面，你需要先搞懂子包依赖在 Monorepo 里到底是怎么被解析的。理解了这套机制，以后遇到任何奇怪的报错，都能自己推出来问题出在哪。
2.1 workspace 协议：省心的本地链接
workspace:是 pnpm 和 yarn 提供的一种依赖协议，它专门用来声明“这个依赖来自本仓库的某个子包”。在包的 package.json 里看起来是这样的：
{ "name": "@my/app", "dependencies": { "@my/utils": "workspace:*" } }这里的*表示直接使用子包当前版本，不需要关注子包版本号具体怎么变化。它解决的就是“子包之间互相引用”的问题。当你执行pnpm install，包管理器会在node_modules里建立一个指向源码目录的符号链接，而不是把子包文件复制一份进去。这样你在packages/utils里改代码，packages/app里立刻就能引用到修改后的内容，不需要每次都重新安装。
我给你的建议是：仓库内部依赖一律用workspace:*，不要用workspace:^1.0.0。因为你自己的子包更新节奏和价值取向跟第三方库完全不同，用*才能在本地开发时永远指向最新源码，避免改完代码还要去手动对齐版本号。到发布的时候，包管理器会自动把workspace:*替换成真实的版本号，不会把你仓库内部协议泄漏到 npm 上。
2.2 依赖提升与幽灵依赖
依赖提升（hoisting）是 Monorepo 依赖机制里最容易被误解的概念。npm 3 以后和 yarn classic 默认把所有子包的依赖尽量提升到根目录的 node_modules 下。好处是避免同一个依赖被安装很多次，坏处是产生了“幽灵依赖”。
我举个例子。packages/app里没声明 lodash，但因为packages/admin声明了 lodash，npm 把 lodash 提升到了根 node_modules，于是packages/app的代码里写import _ from 'lodash'也能正常跑。表面上看起来没问题，实际非常危险：一旦packages/admin某天升级后不再需要 lodash，npm 提升策略发生变化，packages/app就会毫无预兆地报“找不到模块”。
pnpm 的做法完全不同。它默认不提升第三方依赖，而是在每个包的 node_modules 下只放该包显式声明的依赖，然后通过硬链接和符号链接把包连接到全局 store。这样幽灵依赖问题基本被根除，但也会让第一次接触的人疑惑：“我看着 node_modules 里没有 xxx，怎么代码能跑起来？”这就是 pnpm 的机制在起作用，不是 bug，是特性。
2.3 Lock 文件：一个仓库只应该有一把锁
很多从多仓库迁移到 Monorepo 的团队，最大的习惯误区就是把原先的 lock 文件也原样带进来，每个子包锁自己的依赖版本。这在 Monorepo 里是绝对的禁忌。
原因很简单：子包之间存在依赖关系，如果app用的utils版本是 1.2.0，但utils自己的依赖版本又和另一个子包冲突，整个仓库就无法保持一致。单一 lock 文件可以保证任何人、任何机器pnpm install之后，得到的依赖树严格一致。CI 上跑pnpm install --frozen-lockfile，开发机上也跑同样的命令，谁也不会出现“本地能跑，服务器上却挂了”的玄学问题。
所以，你只要用了 workspace，就应该把 lock 文件提升到仓库根目录，并且提交到版本控制里。遇到 lock 冲突，用包管理器自带的 merge 功能去处理，不要手动删除重新生成，否则很容易引入一次无谓的全量依赖升级。
2.4 本地依赖和远程依赖的解析顺序
本地依赖和远程依赖的解析顺序也很关键。当你执行pnpm add lodash --filter @my/app，包管理器先看的是仓库内部的 workspace 包，再看 registry 上的远程包。对于内部依赖，它直接走workspace:协议；对于外部依赖，它根据版本范围去 registry 找，找到以后写入 lock 文件。
如果你安装的是“本地已经下载好的依赖”，比如一个.tgz文件、一个放在vendor/目录里的源码包，或者一个手动 checkout 的第三方库，情况就稍微不同。你可以用file:协议明确指定路径：
{ "dependencies": { "comfyui-local-lib": "file:./vendor/comfyui-lib" } }使用file:协议的包不会进入远程 registry 解析流程，包管理器直接按本地目录做链接和处理，安装速度通常也更快。但这里有个隐患：把绝对路径写进去没用，必须用相对路径，而且一旦这个包发布到 npm，file:协议下的依赖很可能让其他安装者拿不到内容。所以这种写法更适合内部工具链，不要轻易发布到公共源。
3. 实操：在 workspace 里正确安装子包依赖
下面进入真正能照抄的部分。我会按 pnpm 和 npm/yarn 两条线分别给出标准命令，再补充本地依赖安装和缺依赖排查的方法。
3.1 pnpm 下的标准姿势：add --filter
pnpm 提供了一个很实用的--filter参数（简写是-F），用来精确指定往哪个子包安装依赖。命令格式是：
pnpm add hexo --filter @my/blog这条命令的意思是在仓库根目录执行，但只修改@my/blog这个子包的 package.json，把 hexo 添加为它的 runtime 依赖。它不会给其他子包装上 hexo，也不会像在子包目录里直接pnpm add那样只安装局部依赖而破坏整体依赖树。
如果想装开发依赖，加上-D；如果想装到根目录，比如给所有子包共享的构建工具，直接不加--filter：
pnpm add -D typescript pnpm add vite --filter @my/app pnpm add -D eslint --filter @my/app --filter @my/admin注意，--filter可以写多次，也可以支持通配符：
pnpm add lodash --filter "@my/*"这条命令会给所有@myscope 下的子包添加 lodash。听起来很方便，但我个人不推荐轻易使用，因为如果将来子包增多，你未必希望所有子包都依赖同一个第三方库。装依赖这种事，还是越明确越好。
安装内部子包依赖时，我推荐在子包 package.json 里手动写"@my/utils": "workspace:*"，然后执行pnpm install。直接写协议能避免一些包管理器版本差异带来的解析问题，也更方便 code review 的人一眼看出“这是仓库内依赖”。
3.2 npm / yarn workspace 里的安装命令
如果你还在用 npm 7+，对应的命令是：
npm install lodash --workspace @my/app简写形式是-w：
npm install -D typescript -w @my/appnpm 的 workspace 解析依赖的底层逻辑仍然是 hoisting，所以它在大型 Monorepo 里的性能和组织能力都不如 pnpm。但当团队已经标准化使用 npm 时，也可以正常工作。只是要记住，npm 并不支持workspace:*协议，如果你在 package.json 里写了"@my/utils": "workspace:*"，npm 会把它当成一个普通版本范围，然后去 registry 里找名为workspace:*的版本，自然是找不到的。很多人遇到的 “workspace:* 无法解析” 报错，就是拿 pnpm 式的写法套到了 npm 上。
yarn classic 和 yarn berry 的写法不同。yarn classic 支持：
yarn workspace @my/app add lodashyarn berry 也兼容这个命令，但在 berry 里我更推荐从仓库根目录统一管理依赖，靠yarn constraints做依赖规则约束。
3.3 安装本地下载好的依赖包（离线包与 file: 协议）
有些场景下，你不能从公共 registry 下载依赖，比如在内网环境，或者第三方库已经被下载到本地，你想直接安装。这时有两个常见做法。
第一个做法是直接用相对路径引用，适合源码包目录。在子包 package.json 里写：
{ "dependencies": { "@local/comfyui": "file:../../vendor/comfyui" } }然后执行：
pnpm install --filter @my/app第二个做法是引用打包好的 .tgz 文件。这种适合你已经从源站下载了发布包的情况：
{ "dependencies": { "@company/analytics": "file:./vendor/analytics-1.2.3.tgz" } }执行安装后，包管理器会把这个本地包解压到合适的 node_modules 位置，并写进锁文件。需要特别提醒的是，这种file:依赖在团队协作时很容易出问题：成员的代码路径不同、vendor 目录没有被拉取、文件忘记提交等等。所以我通常在团队里约定，file:依赖要么不进仓库，要么必须保证版本管理里包含这个本地文件。
还有一种“伪离线”做法是修改包管理器的安装源指向本地镜像，比如把 registry 指向公司内部部署的私有 registry。这样pnpm install的执行逻辑完全不变，但下载源变了，网速和稳定性反而更好。对于大规模 Monorepo，这也是更推荐的方案，因为 lock 文件里的版本信息不会被破坏。
3.4 遇到“缺少依赖项”该按什么顺序排查
很多人习惯一看到“缺少依赖项”就去搜解决方案。网上搜出来一堆驱动、环境变量、系统组件相关的内容，比如什么realtek-realtekh、ComfyUI 安装本地下载好的依赖、python 在哪个文件配置依赖。这些搜索结果不一定错，但十有八九和你的 Monorepo 问题不在一个层面。
Monorepo 里真正的“缺依赖”报错，绝大多数属于模块解析失败，而不是操作系统层面缺东西。所以排查顺序非常重要。
第一步，先看报错信息里的模块名。比如Cannot find module 'vue'，那你就去对应的子包 package.json 里查，vue 是不是明确写在 dependencies 里。如果没有写，那这就不是“安装失败”，是“你本来就不该用它”，需要补声明。
第二步，检查这个依赖是不是在仓库别的地方存在，只是没提升到当前子包能访问的位置。在 npm 下可以通过根目录npm ls vue查看视图，在 pnpm 下可以用：
pnpm list vue --filter @my/app第三步，如果模块存在，但运行时报错，就要考虑是不是有两个不同版本。比如应用里引用的 vue 和底层某个组件库引用的 vue 不是同一个实例。这个问题后面我单独讲。
遇到这样的“缺少依赖项”，先不要急着乱装一通，冷静定位到具体模块，再决定是补声明、调版本、还是改包管理器配置。
4. 常见问题与排查技巧实录
这一部分，我把这些年实际踩过的坑，以及社区里高频出现的问题汇总一下。每一条都能对应到具体场景，建议收藏当速查表用。
4.1 Cannot find module：十有八九是幽灵依赖
报错长这样：
Error: Cannot find module 'lodash' Require stack: - /workspace/packages/app/dist/index.js很多人第一反应是重新安装，但重新安装十次也没用。这通常是因为代码里用了没有在 package.json 里声明的依赖，之前 npm hoisting 把它恰好提升到了根 node_modules，所以能跑；后来依赖树稍微一变，它就从你的模块解析路径里消失了。
解决方式很明确：在所有子包里面禁止“用了再声明”的反模式，只要代码里有 import 或 require，就必须把它写进当前子包的 package.json。为了从流程上拦住，我建议加 eslint 插件，比如eslint-plugin-import的import/no-extraneous-dependencies规则。它能自动检查当前文件在哪个包目录，如果 import 的模块不在这个包的 dependencies 里，直接报错。
如果是在产生了幽灵依赖之后才排查，最简单的处理就是给对应的子包补上依赖声明，然后重新 install。
4.2 workspace:* 协议在不同包管理器间的陷阱
workspace:*报错最常见的场景，就是团队里有人用 pnpm 写好子包依赖后，又用 npm 跑了一次安装。npm 不认workspace:*，于是从远端拉依赖时找不到，直接报错：
npm ERR! Could not resolve dependency: npm ERR! @my/utils@workspace:* npm ERR! Cannot resolve to a matching version处理办法有两个。要么统一包管理器，你既然用了workspace:*，仓库里就应该用 pnpm 或 yarn；要么如果你必须用 npm，就把依赖声明改成 npm 能理解的方式。npm 的 workspace 对内部依赖的处理方式是自动符号链接，不需要显式写协议，可以直接写"@my/utils": "*"或者具体版本范围。但这样又可能因为版本范围不匹配导致意外，可维护性不如workspace:*。
这个坑提醒我们一件事：Monorepo 是一个团队协作项目，包管理器的选择必须写进项目文档，最好再通过 CI 校验。可以在根目录 package.json 里加packageManager字段：
{ "packageManager": "pnpm@9.0.0" }再配合 corepack，团队成员执行包管理命令时会被强制切换到指定版本，能省掉大量“版本不一致”的破事。
4.3 同一个依赖装了多份，类型冲突怎么查
在 Monorepo 里，同一个版本范围的依赖，因为解析路径不同，经常会被安装成多份。这种场景在 TypeScript 项目里很折磨人：运行时错误一个没有，但类型检查报出一堆Duplicate identifier或者Type 'X' is not assignable to type 'Y'。
查看依赖到底装了几份，pnpm 下用这个命令：
pnpm why react它会列出 react 被哪些包依赖，安装在哪里，版本是什么。npm 下有npm explain react，yarn 下有yarn why react。
找到重复来源后，处理手段通常是利用包管理器的 overrides 或 resolutions 强制指定一个统一版本。pnpm 的写法是在根目录 package.json 里加：
{ "pnpm": { "overrides": { "lodash": "^4.17.21" } } }npm 对应的字段是overrides，yarn 对应的是resolutions。这里有一个原则：能靠 overrides 统一版本，不要去改子包里的版本声明，因为 overrides 只管当前仓库的解析结果，不会影响发布出去的包版本，影响面更可控。
4.4 Vue/React 双实例问题：Monorepo 里的经典翻车现场
在 Monorepo 里，Cannot find module 'vue'反而是小事，更隐蔽的是“组件库插件的类型不对”“对象不是 Vue 实例”“hook 不生效”这类运行时玄学。这类问题的根源通常是同一份 Vue 或 React 在仓库里被装了两份。
举个例子。packages/components是一个开发态下的组件库，它声明了"vue": "^3.4.0"，而packages/app也声明了"vue": "^3.4.0"。由于某些依赖版本解析差异，pnpm 会为两个子包分别安装一份 vue，它们虽然在物理上来自同一个 registry，但符号链接指向的是 store 里的两个不同目录。于是 app 里注册组件时用的是 app 自己的 Vue 实例，组件内部用的却是 components 里的 Vue 实例，插件和响应式系统就错位了。
排查这类问题，最有效的是在运行时打印 Vue 的使用路径：
node -e "console.log(require.resolve('vue'))"分别在两个包目录下执行，如果打印路径不同，就证明存在双实例。然后把两个子包声明里的 vue 版本号统一，再通过 overrides 锁定全局版本。React 同理，require.resolve('react')如果指向不同目录，需要检查是不是有react,react-dom,@types/react版本不一致的情况。
这个问题的本质是“同一依赖的多个副本”，不是某一个具体框架的 bug，所以不管你是 Vue 还是 React 还是别的什么框架，排查思路完全通用。
4.5 Node 版本与包管理器版本不一致
子包安装依赖时报错，有时和依赖本身无关，而是 Node 版本不对。特别是用了一些新语法的新版本依赖，在旧 Node 上会直接编译失败；反过来，太新的 Node 也可能让某些仍在使用旧 API 的依赖行为异常。
我遇到过最典型的场景是：团队里两个人 node 版本差异很大，一个人本地安装一切正常，另一个人却怎么都装不上。用node --version一对比，问题就暴露了。
Monorepo 里推荐在根目录放.nvmrc，内容写上 Node 版本号，比如：
20.11.0然后在文档里要求成员执行nvm use或fnm use切换版本。配合前面提到的packageManager字段，Node 和包管理器版本都能被固定下来。
还有一种很隐蔽的情况：包管理器版本过旧，根本不支持某种新特性。比如早期的 pnpm 版本对 workspace 协议的支持并不完整，升级 pnpm 后问题自动消失。所以遇到解析层面的意外报错，不妨先看一眼pnpm --version，尝试升级到当前大版本的最新版再试。
4.6 网络与缓存导致的安装失败
Monorepo 包数量多，依赖下载量大大增加，网络问题尤其容易暴露。常见的报错有：
ERR_PNPM_TARBALL_INTEGRITY ETIMEDOUT ECONNREFUSED这类问题不是依赖版本错误，是下载链路不稳定或者下载的包校验失败。处理方法，一个是降低并发数：
pnpm install --network-concurrency 1一个是开启离线模式，用本地缓存安装：
pnpm install --offline如果之前已经完整安装过一次，--offline能直接用本地 store 里的包快速重建 node_modules，不发起任何网络请求。这在网络环境差的时候特别管用。但注意，如果 lock 文件里出现了 store 里没有的新包，--offline会失败，这时去掉--offline正常安装一次就行。
还有一类“下载包损坏”问题，通常是因为缓存里的文件不完整。把 pnpm store 清理后重装：
pnpm store prune pnpm install不要在官方文档没让你清 store 的时候手抖去删除全局目录，先prune就够了。
5. 我的实战经验总结
最后这部分，我不打算再重复上面的原理，而是把多年踩坑之后沉淀下来的工作方式直接交代出来，全是干活时能直接用的东西。
5.1 把子包依赖安装固化成一条命令
Monorepo 最大的敌人是“每个包各自为政”。为了防止成员自己跑到子包目录里乱执行 install，我会在根目录 package.json 里定义一套标准脚本。比如：
{ "scripts": { "setup": "pnpm install && pnpm run build", "install:app": "pnpm install --filter @my/app", "clean": "find . -name node_modules -prune -exec rm -rf {} +" } }这样团队里每个人的行为路径都收敛到同一个入口。CI 的构建脚本也直接复用根目录命令，保证本地和远端行为一致。
有几个细节值得留意：clean脚本不建议直接给所有人都开放，因为全量删除 node_modules 后重新安装很耗时，只建议在确实遇到 node_modules 损坏问题时使用；setup脚本里的pnpm build是因为很多子包之间通过workspace:引用时，还需要对方先把源码构建成目标产物，否则直接引用源码在某些脚手架下会出问题。
5.2 别被 Monorepo 绑架：什么时候不用 workspace 反而更好
Monorepo 不是银弹，依赖管理也一样。如果你的所谓“子包”实际上没有任何代码复用关系，只是把几个独立项目放在一个 Git 仓库里，那 workspace 不但帮不上忙，还会增加依赖解析的复杂度。
我见过有人因为“大家都在用 Monorepo”就强行把所有项目塞进一个工作区，结果每个子包仍然互相独立、没有共享代码，反而要应付统一 lock 文件和版本策略带来的额外束缚。这种情况，老老实实用多仓库，或者用不带 workspace 的纯目录结构，成本更低。
还有一类情况是跨语言项目。Monorepo 的 workspace 机制是为 JavaScript/TypeScript 生态设计的，如果你的仓库里既有 Node 子包，又有 Python、Go、甚至 ComfyUI 这种带独立依赖环境的第三方工具，不要指望pnpm install能把所有语言的依赖一并解决。Python 该用 venv 还是用 venv，虚拟环境该建还是要建。Monorepo 能统一的是源码组织方式，不是所有语言的依赖管理方式。
5.3 最后的几条血泪建议
第一，子包的 dependencies 必须完整声明。这是 Monorepo 依赖管理里最重要的纪律。宁可多声明用不到的依赖，也不要让代码偷偷使用未声明的依赖。后者带来的幽灵依赖问题，排查代价远高于几行声明。
第二，所有内部子包引用，统一使用workspace:*，不要在内部依赖上写死版本号。每次改内部包的版本再逐个去上游同步版本号，纯属浪费时间。
第三，lock 文件是仓库资产，不是负担。它提交进 Git，能保证团队所有成员和 CI 环境完全一致。遇到锁文件合并冲突，就老老实实重新pnpm install让包管理器处理，不要手动删掉锁文件，否则很容易在升级依赖的同时引入一堆你根本没发现的破坏性变更。
第四，遇到“缺少依赖”报错，先报模块名，再定位 package.json，再看 lock 文件，最后才考虑重装。按这个顺序排查，90% 的安装问题都能快速弄清原因。
回到最初的问题，子包安装依赖其实只有三条准则：在仓库根目录统一管理，依赖声明全部显式化，内部依赖走 workspace 协议。把这三件事做扎实，Monorepo 带来的收益会远大于它引入的管理成本。真实项目里，依赖问题几乎都不是“安装不上”，而是“组织方式错了”。希望这篇文章能让你少走几条弯路。
