我最早接触 Monorepo 这个词的时候以为是把所有项目的代码一股脑塞进同一个仓库这么简单。真正动手搭了一套工程体系之后才发现Monorepo 的实现原理远比代码放一起复杂得多——它牵扯到依赖解析、构建图、增量缓存、影响面分析后面还有一整套任务编排机制。这篇文章不打算讲某个具体工具的配置教程而是想从工程实现的角度把 Monorepo 这套东西是怎么跑起来的拆开看。适合准备把多仓库改造成 Monorepo、或者想真正理解 Turborepo、Nx、Bazel 这类工具底层逻辑的开发者。1. Monorepo 不是代码收纳盒先搞清楚它到底解决什么问题1.1 我一直觉得 Monorepo 就是所有代码放一个仓库直到我在 A 项目里改了四十七个包这是很多人对 Monorepo 的第一印象也是最大的误解。把代码放进同一个仓库只是表象Monorepo 真正解决的是多项目协作时的依赖同步和变更一致性问题。我见过一个团队改造前有十来个独立仓库业务包、组件库、工具库、Node 服务、前端应用各放一处。表面上挺干净真开发起来全是麻烦。前端应用依赖组件库的某个未发布版本就得先在组件库里发一个 beta 包然后改前端里的版本号再安装。一个接口联调涉及两三个项目就得同时开好几个终端窗口发好几个包。改点公共逻辑要在三四个仓库里同步提交只要漏一处线上就是事故。这种模式叫 MultiRepo多仓库每个项目的依赖关系、版本管理完全独立。它给你一种模块化很清晰的错觉实际代价是跨项目集成变成一场持久战。Monorepo 的思路是把有耦合关系的项目放进同一个仓库统一管理。这样前端应用和组件库可以同时改、同时提交、同时验证代码之间的改动是原子的——要么一起进主干要么都不进。依赖也从发到远程仓库再拉回来变成直接引用工作区里的源码路径省掉了一整条发布-安装链路。1.2 从 MultiRepo 到 Monorepo真正痛的是跨仓库协作要说清楚 Monorepo 的价值得先还原一下 MultiRepo 下跨仓库协作的真实场景。假设你有三个仓库utils公共工具集、components业务组件库、app业务应用。开发新功能时app 需要 components 里还没发布的新组件components 又依赖 utils 里新增的工具函数。在 MultiRepo 下流程是这样的在 utils 里写完新函数提交发版等 npm 同步。在 components 里安装 utils 新版本写完新组件提交发版等 npm 同步。在 app 里安装 components 新版本终于开始写业务代码。开发中发现问题回到第 1 步重来。这里最折磨人的不是操作步骤多而是样本空间爆炸——任何一个包的版本组合都可能出问题。utils 发了三次版本、components 发了两次版本app 也许刚锁了一个组合另一个团队又踩了另一种组合的坑。多仓环境下版本组合数是乘数增长的这就是依赖地狱的根源。Monorepo 用 workspace 机制直接从结构上消灭掉这个问题。所有包都在一个仓库里依赖关系指向工作区内的路径构建、测试、发版都是一条流水线下来不存在N 个仓库之间的版本组合这个命题。1.3 原子提交与统一依赖Monorepo 收益的底层来源理解了痛点回报就自然浮现了原子提交一个需求涉及的跨包改动可以在一个提交里完成代码评审时能看到完整的变更上下文而不需要打开三四个 PR 来回对齐。出问题时也能统一回滚。统一依赖版本公共依赖的版本在仓库根统一管理不存在包 A 和包 B 各自锁了不同的 React 版本这种分裂状态。这对排查安全漏洞、统一构建策略都友好得多。跨项目重构成为可能改一个公共 API 的签名直接用 IDE 全局重构然后跑一遍全量测试。MultiRepo 下这种操作基本不可能完成因为别的仓库根本不在你手里。这些收益听起来美好但实现起来有一个关键问题代码集中了怎么保证它还像以前一样能稳定、高效地构建和部署答案就是 Monorepo 的工具链体系——依赖解析、构建图、增量缓存、任务编排。接下来逐步展开。2. 依赖解析与构建图Monorepo 实现原理的引擎2.1 workspace 协议与符号链接pnpm 为什么用 link 而不是路径先说一个我碰到的反直觉案例。搭建 workspace 时我看到有人直接在 package.json 里把本地依赖写成my/utils: file:../utils觉得挺合理——不就是相对路径吗实际跑起来各种诡异问题utils 里的代码改动不能实时生效要重新安装、多个包引用同一份 utils 时出现多份实例、构建产物路径混乱。后来查了 yargs 和 pnpm 的实现才明白现代 Monorepo 工具做依赖链接时用的不是简单路径替换而是符号链接symlink机制。以 pnpm 为例它的 workspace 布局是这样的所有真实文件都在仓库根目录的node_modules/.pnpm里每个包按版本号放在独立目录下。每个包的node_modules里只放它自己的直接依赖的符号链接指向.pnpm里的真实文件。workspace 内包之间的依赖同样通过符号链接指向对应包的真实源码目录。root/ ├── node_modules/.pnpm/ │ ├── myutils1.0.0/node_modules/my/utils/ - 真实文件 │ └── mycomponents1.0.0/node_modules/my/components/ - 真实文件 ├── packages/ │ ├── utils/ │ ├── components/ │ └── app/这样做有两个直接好处内容只存一份磁盘占用从每个包各装一份变成仓库统一一份在依赖多的大仓库里能省出几十 GB。依赖关系可追溯pnpm 独有的严格 node_modules 结构会让幽灵依赖无处遁形——你没法直接 require 一个没写在 package.json 里的包。这一点对工程整洁性帮助极大。yarn 和 npm 的 workspace 也会做类似的符号链接只是目录结构和链接策略略有差异原理是同源的。关键实操点本地开发时如果你改的是 utils 包的源码app 里不需要重新 install符号链接指向的是真实目录改动即时可见。但前提是构建和运行时的解析路径一致——esbuild、Rollup、Webpack 的 resolve 配置里符号链接不能被 resolve.symlinks 关掉否则运行时跟构建时的模块解析结果会不一致出一些很隐蔽的问题。2.2 构建依赖图 DAG从 package.json 出发的项目拓扑符号链接解决的是代码怎么互相引用的问题但 Monorepo 里还有一个更复杂的问题哪个包要先构建哪个能并行改了一个包哪些包会被影响答案在依赖图里。每个包的 package.json 里声明了 dependencies这些声明关系构成了一个有向无环图DAGapp ├── components │ ├── utils │ └── icons └── utils工具要做的事情很简单扫描所有包的 package.json把包名和依赖关系读出来构建成内存里的图结构。每个节点是包每条边是依赖关系。这个图是后面一切机制的基础。拓扑排序决定任务执行顺序逆向追踪决定影响面图的哈希决定缓存是否命中。所以我一直觉得理解 Monorepo 工具链的关键不是学命令而是理解这张图。Nx 和 Turborepo 在这里做了一层更细的工作它们不只看 package.json 的依赖声明还会分析源码里的 import/require 语句生成细粒度的文件级依赖图。package.json 声明的是这个包依赖谁源码分析揭示的是这个文件实际用到了谁。后者更精确但也要多花构建时的分析成本。2.3 拓扑排序与并行任务调度为什么慢项目会被卡在依赖链上有了图任务执行就顺理成章了。构建时工具做拓扑排序——保证每个包都等到它的依赖构建完成后才开始构建。拓扑排序的经典实现是 Kahn 算法1. 统计每个节点的入度依赖它的上层包数量 2. 入度为 0 的节点先入队 3. 取出节点构建完成后把它下游节点的入度减 1 4. 入度降到 0 的节点继续入队 5. 重复直到所有节点构建完成我最初犯过一个典型的错误给 app、components、utils、icons 这几个包的手动构建脚本设计了一个固定顺序以为从上往下跑就行。结果加了一个新包之后发现它有独立的依赖分支固定顺序完全失效。改为拓扑排序之后无论仓库里有多少包依赖关系怎么变都能自动排出合法顺序。并行度和拓扑排序是天然框架但要注意一点并行度过高不等于高效。CPU 核数是有限的构建任务也大量占用 I/O一个机器上同时跑 16 个构建任务大部分时间都花在进程切换和资源争抢上。Nx 和 Turborepo 都允许限制并发数我实际测试下来8 核机器上并发设 4~6 比较合理吞吐量最高卡顿最少。3. 增量构建与产物缓存让这套机制跑得快的关键设计3.1 内容寻址缓存hash 里到底装了哪些东西Monorepo 只是把代码集中了如果每次构建都全量重来那速度会比多仓库还慢。真正的性能利器是内容寻址缓存CASContent-Addressable Storage。核心思路每个构建任务对应一组输入和输出工具根据输入计算一个 hash用 hash 作为缓存 key把输出产物存起来。下次跑任务前重新计算 hash如果和上次一样直接取缓存产物任务本身跳过。听起来简单实现时最考究的是hash 里到底要装哪些东西。我总结过一份清单缺一不可该包源码文件的 hash文件内容、文件路径、文件 mtimepackage.json 里 dependencies 字段依赖链上所有上游包的 hash 值构建配置tsconfig、babel.config、webpack 配置等环境变量里构建相关的值包管理器的 lockfile 文件 hash这也是我踩过的大坑。有段时间 CI 上缓存命中率忽高忽低排查了半天发现是环境变量里混了一个构建时间戳每次 hash 都变缓存形同虚设。后来我把参与构建的环境变量白名单化只把NODE_ENV、BUILD_VERSION这类固定变量纳入 hash命中率才稳定在 85% 以上。3.2 本地缓存与远端缓存CI 里缓存命中率为什么忽高忽低增量构建分两层本地缓存和远端缓存。本地缓存存在每台机器的磁盘里用于本地开发场景——你改了 A 包B 包没动B 的构建直接命中缓存。这个方案的局限很明显换一台机器、清一次node_modules、或者在 CI 上跑本地缓存就全失效了。所以大型仓库都会配套远端缓存缓存放在共享存储上对象存储、NFS、或者工具自带的分布式缓存服务。我在配置远端缓存时遇到的典型问题有三个基本覆盖了这个环节能踩的坑缓存 key 的载体不一致。本地开发拿 MAC 上的文件 hash 算 keyCI 是 Linux 环境文件的换行符、权限位、符号链接目标解析都可能不一样导致同一份代码算出不同的 hash远端缓存命中率骤降。解决思路是构建脚本里统一做归一化——比如构建前统一格式化、统一权限位。产物含绝对路径。构建产物里写死了/Users/xx/packages/app/dist缓存到远端后发给另一个环境路径全部失效。这种问题最隐蔽因为本机验证永远正常。处理办法是构建产物里一律使用相对路径或者在配置里指定路径重写。缓存存储没有做容量控制。产物越积越多存储成本水涨船高。Nx 和 Turborepo 的远端缓存都支持配置保留策略我会设成一个合理的窗口期比如 7 天超过自动清理。3.3 任务编排的优先级策略先跑依赖树底部的包增量缓存能跳过没改的包但第一次全量构建时任务编排的优先级策略仍然值得琢磨。工具默认的调度逻辑通常是能并行就并行但这会导致一个问题底层包还没建完上层包已经在干等。理想的策略是按依赖深度分层调度——先跑所有叶子节点下层的基础包再逐层向上每一层内部并行。举一个实际场景。仓库里有 20 个包其中 10 个是最底层的基础库。如果调度策略不是按层推进而是什么任务 ready 就先跑什么10 个基础库建完后才会轮到中间层看起来并行度满了但实际等待链条拉长。按层推进后每一层内的并行度依然很高但整体进度更符合直觉也更容易预测。Turborepo 的--graph命令可以可视化依赖图Nx 也有nx graph。我建议无论用哪个工具第一次搭 Monorepo 时一定跑一次依赖图出来看一眼确认图上没有不合理的绕圈引用也没有本该独立却被人为耦合的包。图的质量决定后面所有机制的上限。4. 变更集与影响面分析一次改动如何精确锁定受影响包4.1 changed files → affected packages 的计算链路增量构建回答的是这次构建能复用哪些缓存影响面分析回答的是这次改动会影响哪些包、哪些测试、哪些部署任务。两者关联但不同。链路是这样的拿到当前改动涉及的文件列表git diff 的结果。把文件路径映射到所属包——文件在packages/app/src/xxx.ts就归属 app 包。沿着依赖图反向遍历找出所有依赖这些包的上游包。第二、三步不难理解第一步里有个细节工具普遍会做一个基线快照处理。你在一个分支上改了一周跟主干的 diff 可能非常大里面夹杂着无关的合并冲突、格式调整。这时候要看的是相对于基线分支比如 main或者上一次 merge-base的差异而不是当前分支的全部 commit 改动。Turborepo 的--since参数就是这个作用Nx 的 affected 命令会自动解析与基线的差异。4.2 依赖方向的传递直接影响、间接影响与测试范围很多人做影响面分析时只考虑到直接依赖比如改了 utils就重新跑一下依赖 utils 的 components 包的测试结果漏掉了依赖 components 的 app 包里的组件测试线上直接翻车。这里的规则是沿着依赖图传递一个包被改动后所有直接依赖它的包都要重新验证这些包的上游也要继续传递。我习惯在项目里标注三种影响级别直接依赖package.json 声明里直接依赖目标包的包。间接依赖通过上游包传递依赖到目标包、但自身没有直接声明的包。反向依赖被目标包依赖的下游基础包——这类包通常不需要重新验证除非发生了 API 破坏。影响面计算的实际用途是筛选测试集。改动只涉及两个包时没必要全仓库跑几百个测试套件只跑受影响包的测试就够了。这个机制在 CI 配置里体现为条件化流水线——affected 计算出来的测试任务才挂进流水线其余的跳过。4.3 只重新构建受影响包的实践手动验证与工具辅助Nx 的 affected 命令做了很完整的工作nx affected:build --basemain nx affected:test --basemainTurborepo 的等价做法是通过--filter或--since配合任务声明实现。但我见过不少团队在用工具之前先手动搭过一套 diff 校验脚本反而加深了对这个机制的理解。脚本逻辑大约是这样1. git diff --name-only main得到 changed_files 2. 每个文件路径匹配到所属包通过目录前缀 3. 从这些包出发DFS 遍历依赖图上游收集 affected_packages 4. 对 affected_packages 里的每个包执行测试/构建命令自己实现过一遍之后再看 Nx 的 affected 实现就不会觉得它是黑盒了。它本质上就是把上面这套逻辑做成标准服务同时接入 file watcher 做增量分析并在 CI 环境里自动识别基线分支。5. 撑起巨型代码库的工具链Bazel/Turborepo/Nx 各自的做法5.1 三种实现路线的取舍Bazel 的严格沙箱Turborepo 的缓存Nx 的图提到 Monorepo 实现原理绕不开几个代表工具。它们解决的是同一张依赖图但骨架架构范式完全不同。Bazel是这条路线的鼻祖思路极其硬核。它的底层模型是全面内容寻址的构建系统——一切产物都由输入内容 hash 决定构建动作在沙箱里执行。沙箱保证了构建的完全可重复性也因此才能做到可靠的缓存和并行。代价就是学习曲线陡峭、配置繁琐而且沙箱对自定义脚本的限制很多——项目里如果有脚本需要访问网络、系统全局资源沙箱会直接拦掉。Turborepo走的是轻量路线。它不会重造构建机制而是包装现有的 npm scripts、package manager 任务通过 hash 计算和缓存跳过未变化的构建任务。上手快心智负担低适合大多数业务团队。代价是它不做严格沙箱可重复性依赖团队自身的规范性。Nx在这两者之间。它提供更强的图分析和依赖追踪能力在 package.json 依赖之外还能分析源码 import 关系来构建更精确的模块图。Nx 还提供集成测试、lint、构建的原子化任务编排公司内部已经有不少团队拿它管理千级仓库。选型逻辑我给不出哪个最好的答案只能说说使用体会团队规模小、依赖简单、想快速解决多仓改单仓问题Turborepo 一天内能跑起来收益立竿见影。仓库规模上千包、构建优化要求极高、团队能投入全职基建人力Bazel 值得认真评估。业务复杂、任务编排需求多、希望工具提供更完整影响面分析能力Nx 是最均衡的选择。5.2 远程执行与分布式缓存一个有边界的判断继续往深处挖Bazel 讲远程执行Remote ExecutionTurborepo 讲远端缓存Remote CacheNx 也支持分布式缓存和远程任务执行。这两者的差异很容易混淆。远端缓存的本质是产物共享机器 A 构建好 package-a产物上传到共享存储机器 B 遇到相同 hash 时直接下载产物不做任何计算。远程执行的本质是算力共享构建任务被分发到远端执行集群跟本地 CPU 个数无关机器本地只负责提交任务、接收产物。一个团队刚开始接触 Monorepo 时往往先看效果好的远端缓存——因为它带来的提速立竿见影。但踩过几次坑就会发现缓存只对未变化的代码有效一旦大规模重构缓存全部失效所有机器都得重新算一遍。远程执行才是终极解法因为它提供了真正的弹性算力——但前提是构建必须是沙箱化的、可并行的能把模板化的构建命令交给任意一台机器重放。这两者之间有个判断边界如果你的构建不能保证可重复性远程执行就是灾难。5.3 Monorepo 不适用场景什么时候果断别用聊了这么多原理最后说点反方向的。Monorepo 不是银弹以下场景我宁可维持多仓库强平台隔离的代码。比如 iOS 原生、Android 原生、嵌入式固件、Windows 客户端它们的工具链、依赖管理器、构建系统完全独立强行放一个仓库里只会让流水线配置变得极度复杂。独立发布节奏的纯库。发布节奏独立且没有跨库改动的库用单一仓库维护只是增加仓库体积和首屏 clone 时间。团队协作边界模糊时。如果两个团队没有共同的代码归属感只有抽象接口关联Monorepo 很容易演变成一个谁都能改别人代码的混乱状态代码所有权保护反而成了空话。我给的建议是Monorepo 最合适的应用对象是有明确依赖关系、经常跨层联动的业务代码集合。纯工具库、平台原生代码、没有关联的独立站点该独立就独立。回到实现原理本身Monorepo 的核心链路说到底就是三条构建依赖图让系统知道包与包怎么互相影响内容寻址缓存让系统知道哪些东西可以复用拓扑编排让系统知道该先跑什么后跑什么。理解了这三条无论你用什么工具都只是在同一个骨架里选一套皮肤而已。我个人在实际操作中的体会是Monorepo 的基建改造不用一步到位。先把 workspace 跑起来再逐步导入增量缓存、影响面分析最后才考虑远程执行。这套路演示走通了弹性才真正属于你。
