2025 年春天我接手一个项目,前端摊在 6 个仓库里:一个组件库、一个工具函数库、一个请求封装库,外加三个业务应用。仓库名字都起得规整,README 里还画了依赖图,看着像那么回事。可实际改一个按钮的颜色,流程是这样的:改组件库、发一个版本;改工具库——因为它把组件库的版本写死了;三个业务应用各提一个 PR 升级依赖,各跑一遍回归;最后约三个上线窗口。一个颜色,两周。
这事不能怪哪个人懒,也不完全是流程繁。根子在于仓库的边界画在了依赖高频变动的位置上。组件库、工具库和业务应用之间的依赖一周要变好几次,而每跨一次 Git 仓库,就得付一遍「发布、升级、验证」的固定成本。这个成本跟改动大小无关:改一行颜色和重构一个组件,仪式一样多。改动越频繁,浪费越成倍放大。
这篇讲我们怎么把 6 个仓库收成 1 个:当时的约束是什么,比较了哪几种做法,为什么最后选 pnpm workspace 加 Turborepo,落进去之后又踩了哪些坑。我不打算写「monorepo 的十大优势」那种清单——如果你只有两个包、五个人,monorepo 大概率是负收益,文章后半段会说清这条线在哪。
先把问题钉死,别急着选工具
「要不要上 monorepo」这个问题本身没法回答,它太抽象了。能回答的是四个更具体的问题:哪些包变化频率高?谁是谁的消费者?各团队的发布节奏是否必须独立?权限和合规要不要按仓库隔离?
我们盘了一遍现状,得到四条硬约束,后来每次选型争论都回到这四条上:
| 约束 | 具体数字 | 对方案的影响 |
|---|---|---|
| 团队规模 | 15 人,3 条业务线,组件库每周 1–2 次改动 | 跨仓库发布是高频动作,必须压缩 |
| CI 时间 | 单仓库全量 18–25 分钟,三个应用串行 | 需要只跑受影响的包,且要能缓存 |
| 存量系统 | 两个老 AngularJS 后台不能动 | 新方案必须能和外部仓库共存 |
| 开发环境 | Windows 与 macOS 混用 | 软链、路径大小写、脚本跨平台都要考虑 |
还有一条软约束没写进表里:没人愿意学一套新框架。团队里能把 webpack 配置从头看懂的人不超过三个,再引入一套带自己 DSL 的构建系统,日常维护会迅速集中到一两个人身上。人一忙,这套系统就开始腐烂,最后变成「只有某某会弄」的黑盒。
画出来才发现荒诞:链条上有四段,其中三段的工作量由仓库数量决定,和改动本身无关。我们要砍的是这三段,不是让每段跑得更快。
三种做法,各自要付什么代价
当时摆在桌面上的其实是三张牌,我把它们连同真实的成本一起列出来。选型文档里只写优点的那种,最后都会在落地时反噬。
A. 多仓库 + 私有 registry(现状)
好处:边界清晰,权限天然隔离;单个仓库小,clone 和装依赖都快;某个库挂了不影响别人发版。
代价:跨包改动必须发版;版本组合开始爆炸,组件库 2.3 配工具库 1.8 配请求库 0.9 再用在应用 A 上,这个组合没人说得清是否被测过;本地联调只能靠 npm link 或 yalc,link 完软链、依赖树、路径解析全是新问题,而且这些问题只在别人的机器上出现。
B. 单仓库 + workspace
好处:一次提交改完所有包,应用直接引用源码,不需要发版;依赖装一次,版本天然对齐。
代价:仓库变大,CI 默认全量跑;包与包之间的边界只能靠人守,谁都可以跨包 import;node_modules 的结构一换,历史遗留的隐式依赖会集中暴露。
C. 单仓库 + 任务编排(Turborepo / Nx)
好处:在 B 之上只跑受影响的包,任务结果可缓存,CI 时间能压到几分钟;任务依赖关系显式声明,不再靠脚本里手写顺序。
代价:要维护任务图和缓存配置;缓存键配错会出现「本地过、CI 挂」这类最难查的问题;Nx 的生成器和插件体系更强,也更容易把团队绑在它的抽象上。
D. 多仓库 + 同步发布(我们试过的过渡方案)
做法:仍然是多个仓库,但用固定版本号、脚本一键发布所有包,减少人工等待。
代价:仪式的次数没变,只是每步快了点。我们试了两个月,组件发布频率从每周 1 次涨到 3 次,业务升级的滞后反而更严重——因为升级要跑回归,没人愿意为一个小版本去跑一次全量回归。
D 方案值得单独说一句,因为它看起来很聪明,也很容易让人产生「已经在改进了」的错觉。发布自动化只压缩了等待时间,没有消除跨边界这件事本身。只要一次改动仍然需要 N 个仓库各自合并、各自验证,N 越大,事务性越差,中途失败的概率越高。
为什么最后是 pnpm workspace + Turborepo
结论是 B 加 C 的组合,具体到工具是 pnpm 9.x + Turborepo 2.x,Node 20 LTS。三个判断依据,按重要性排。
第一,不用 npm 或 yarn 的 workspace。现有仓库大多已经在用 pnpm,lockfile 是现成的;更关键的是 pnpm 的 node_modules 是严格结构,没写进 package.json 的包根本 import 不到。这条限制会逼我们把历史遗留的隐式依赖一次性理清。短期很痛,第一周大概冒出来十几个 Cannot find module;长期省事,因为这类问题在换构建工具、升级大版本时一定会集中爆炸。npm 和 yarn 的扁平化提升会把问题藏起来,藏得越久,账单越大。
第二,不用 Nx。Nx 的任务图、受影响范围计算、代码生成确实更成熟,社区插件也多。但它要求你按它的方式组织项目、用它的插件体系,配置项几百个。我们只有 8 个包,任务类型就 build、test、lint 三种,Turborepo 一个 JSON 文件就够。工具的能力要和问题的复杂度匹配,多出来的能力最后都会变成维护成本和新人门槛。
第三,不搞「多仓协同」。有人提过 meta 仓库加 git submodule:一个空仓库把其他仓库串起来,看着像 monorepo。我们否了。submodule 的版本指针需要手动推进,本质上是把发布仪式换了个名字,而且新同事 clone 完经常忘记 --recursive,打开就是一堆空目录。git subtree 更复杂,合并冲突能把人逼疯。
# pnpm-workspace.yaml
packages:
- "apps/*"
- "packages/*"
- "!**/test/**"
// turbo.json
{
"$schema": "https://turbo.build/schema.json",
"tasks": {
"build": {
"dependsOn": ["^build"],
"outputs": ["dist/**"],
"env": ["NODE_ENV", "VITE_API_BASE"]
},
"test": { "dependsOn": ["build"], "outputs": ["coverage/**"] },
"lint": { "outputs": [] }
}
}
^build 的意思是「先构建我依赖的包」,任务图不用手写。这一行是整个方案的核心:它把原来靠文档和口头约定维持的构建顺序,变成了可执行的声明。
env,否则不进缓存键。我们在这上面栽过一次:本地改了 .env 里的接口地址,构建仍然命中旧缓存,产物里是旧地址,页面看起来正常,请求全打到测试环境。这类问题不报错,只让人怀疑人生。落地之后真实踩的坑
合并第一周很爽,第二周开始还债。下面这些坑按出现顺序排,基本是 monorepo 的必修课,跟用哪套工具关系不大。
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
本地能跑,CI 报 Cannot find module 'dayjs' | 幽灵依赖:代码 import 了没在 package.json 声明的包,过去靠扁平化侥幸能用 | pnpm why dayjs,再全局搜 import 语句 |
| 改了 packages/ui 的源码,apps/web 毫无变化 | 应用依赖写的是 registry 版本号而不是 workspace:*,或命中了旧构建缓存 | 看应用 package.json 的依赖写法;turbo run build --dry-run=json |
| CI 缓存命中率只有两成,时间没降 | 缓存键里混进了无关输入,或 CI 每次 install 都改写 lockfile | 对比两次任务的 hash 输入;看 CI 是否有脚本动了 lockfile |
| 上线后某个应用报 Invalid hook call | 不同包各自声明 react,peerDependencies 没约束,装出了两份 React | pnpm why react;pnpm list -r --depth 1 |
| 本地构建成功,CI 失败且无法复现 | 环境变量没进 env 声明,或 CI 的 Node 版本和本地不同 | 检查 turbo.json 的 env/globalEnv;比对 node -v 与 .nvmrc |
| 安装时间从 3 分钟变成 12 分钟 | pnpm store 没跨项目复用,或杀毒软件在扫 node_modules | pnpm store path;看 CI 是否每次清空缓存目录 |
| 改 A 包,B 包测试挂了,但 B 的代码没动 | 包之间共享了可变状态或全局单例,测试没隔离 | 看测试是否各自 reset 模块;用 vitest 的 isolate 配置 |
迁移本身也需要策略,不能一上来就把六个仓库倒进一个目录。我们的做法是先合两个依赖最紧密的包(组件库和工具库),让业务应用继续从 registry 装包;跑一个月,确认构建、发布、缓存都稳定,再把业务应用搬进来。每一步都能回退,出问题时损失可控。一次性大爆炸式迁移,出问题时你连「是合并导致的还是本来就有」都分不清。
这里最值得展开的是幽灵依赖和版本漂移,因为它们不会立刻报错,而是以「偶尔」「某台机器」「某个路由」的形式出现,排查成本极高。
幽灵依赖的典型场景是:包 A 依赖了 lodash,包 B 没声明 lodash 却直接 import。扁平化安装时 lodash 被提到顶层,B 能跑;换成 pnpm 的严格结构,B 立刻报错。这个报错是好事,它把隐式契约变成了显式声明。真正麻烦的是反向情况:B 声明了 lodash 3,A 用的是 lodash 4,两个版本同时进 bundle,体积涨了 70KB,功能还各自正常,只是某个 debounce 的行为不一样。这种问题只能靠 pnpm why 加产物分析来抓。
版本漂移的根源是包各自声明框架版本。解决办法只有一个:把 react、react-dom、typescript 这类「只能有一份」的依赖提到根 package.json,子包用 peerDependencies 声明范围。pnpm 有 overrides 可以强制统一,但那是止痛药,不是根治。
仓库结构不是画出来的,是长出来的
很多人上手第一件事是画一棵漂亮的目录树,分十几层,每层都有 README。我们最后的结构很朴素,按「谁被谁依赖」分五层,不按技术栈分。技术栈会变,依赖方向不容易变。
层级规则压缩成三句话:apps 可以依赖 packages;packages 之间只允许 shared ← ui 这种单向关系;config 只能出现在开发依赖里。规则不能靠自觉,我们用 dependency-cruiser 在 CI 里卡。刚合并时靠 code review 守,三周后就出现了 ui 反向 import 业务 store 的事——原因很简单,那次需求赶,review 的人也不熟。
发布:monorepo 最容易被低估的部分
合并仓库只解决了「改」,没解决「发」。业务应用可以整体部署,但组件库、工具库如果还要给外部项目或老仓库用,就仍然需要版本号。我们最后用 changesets:每个 PR 附带一个 markdown 描述这次改动的影响级别(patch / minor / major),合并时汇总,发版时一次性升版本、生成 changelog、打 tag。
有两条硬要求。第一,packages 之间的依赖一律写 workspace:*,发布时由 changesets 替换成真实版本号;写死版本号等于把仪式又请回来了。第二,major 变更必须带迁移说明和 codemod,否则老应用会永远卡在旧版本——这比发不出新版更糟,因为它会让「升级」变成一件需要立项的事。
发布还有一个容易漏的点:回滚。业务应用的部署回滚只是切流量,但包的回滚要重新发一个旧版本——不能 unpublish,因为可能已经有人装了。我们的约定是「发现问题就发一个补丁版退回」,并把每次 breaking 变更的原因和影响面记在版本说明里,避免下一次发布又踩同一个坑。这套流程写进值班手册,谁值班谁照做,不靠记忆。
边界与代价:什么时候不该做
monorepo 不是架构升级,它是在用「仓库之间的协作成本」换「仓库内部的隔离成本」。这条交换线大致可以这么划:
五个人以下、两个包,不要做。跨包改动一周不到一次,发版仪式完全扛得住,多一层 workspace 只是多一层心智负担。省下的时间,抵不过配置和培训的成本。
包超过 80 到 100 个、业务线超过五条,Turborepo 会开始不够用。任务图和受影响范围计算会变成瓶颈,这时候 Nx 或者 Bazel 才有意义。注意是「开始不够用」时才换,不是一开始就上最重的。
发布节奏必须独立的团队,不要硬塞。对外 SDK 和内部应用放一个仓库,会让「谁能发版、谁批 major」变成政治问题。可以拆成两个 monorepo,不必追求大一统。
权限、合规、部署隔离有硬要求,就别合并。一个仓库一份权限,做不到按目录授权,这个方案从合规上就不成立。
还有一层隐性代价容易被忽略:仓库变大之后,IDE 索引、git status、全局搜索都会变慢,全量 CI 从 20 分钟变成 40 分钟。这些不是「优化一下就好」的小事,它们每天都在消耗所有人的注意力。真正的收益必须大到能覆盖这部分持续损耗。
今天就能动手的五件事
不建议先搭一套新仓库再迁移。先用半天把成本量化,数字会替你做决定。
一、数一次仪式。挑最近一次跨包改动,数清它经过几个 PR、几次发布、几次回归、一共等了几天。这个数字就是 monorepo 能省下的上限。如果算出来是两天以内,别折腾。
二、找幽灵依赖。在现有仓库里临时删掉 node_modules 重装,然后跑构建。所有冒出来的 Cannot find module,都是过去靠提升侥幸活着的隐式依赖。先把清单列出来,再决定要不要合并。
三、看缓存到底命不命中。用 turbo run build --dry-run=json 看每个任务的 hash 和 cache 状态,连续跑两次,第二次应该是 FULL HIT。不是的话,顺着 hash 输入找是哪个文件或环境变量在变。
四、写一条依赖方向规则。用 dependency-cruiser 配一条「packages/ui 不能依赖 apps」的规则,先只报警不阻断,观察一周有多少违规。违规数量直接反映团队对边界的理解程度。
五、完整走一遍发布。用 changesets 在一个分支上写 changeset、合并、发一个 0.0.x 的测试版本到私有 registry。走完你就知道流程里最烦的是哪一步,通常不是发版本身,而是「谁知道该发哪个版本」。
小结
monorepo 真正解决的问题只有一个:跨包改动不再需要发版。其他好处——统一规范、复用配置、原子提交——都是顺带。它带来的新问题是构建编排、依赖约束和发布治理,这些问题不会自己消失,只会从「跨仓库沟通」变成「仓库内的规则」。
仓库收拢之后,下一个暴露出来的问题几乎一定是产物:所有包打成一个 bundle,首屏越来越大,改一行代码缓存全失效。下一篇讲拆包与摇树,正好接着这里往下走。