Monorepo，大型前端项目管理模式实践

▐  发展历程

1. 代码和配置很难共享：每个仓库都需要做一些重复的工程化能力配置（如 eslint/test/ci 等）且无法统一维护，当有工程上的升级时，没能同步更新到所有涉及模块，就会一直存在一个过渡态的情况，对工程的不断优化非常不利。
2. 依赖的治理复杂：模块越来越多，涉及多模块同时改动的可能性急剧增加。如何保障底层组件升级后，其引用到的组件也能同步更新到位。这点很难做到，如果没及时升级，各工程的依赖版本不一致，往往会引发一些意想不到的问题。
3. 存储和构建消耗增加：假如多个工程依赖 pkg-a，那么每个工程下 node_modules 都会重复安装 pkg-a，对本地磁盘内存和本地启动都是个很大的挑战，增加了开发时调试的困难。而且每个模块的发布都是相对独立的，当一次迭代修改较多模块时，总体发布时效就是每个发布流程的串联。对发布者来说是一个非常大的负担。

▐  单体应用架构 Monolithic

项目初期起步阶段，团队规模很小，此时适合「单体应用」，一个代码仓库承接一个应用，管理成本低，最简力度支撑业务快速落地。

此时目录架构大概长这样：

project├── node_modules/│   ├── lib@1.0.0├── src/│   ├── compA│   ├── compB│   └── compC└── package.json

优点：

1. 代码管理成本低

2. 代码能见度高（无需额外的学习成本）

3. 发布简单，链路轻便

缺点：

1. 代码量大了后，调试、构建效率显著下降

2. 无法跨项目复用

▐  多仓多模块管理 Multirepo

团队规模变大，人员分工明确，单体应用的缺点会愈发突出，此时 「Multirepo」就更适合。模块分工更明确，可拓展可复用性更强，调试构建发布能力也有一定提升。

此时目录架构大概长这样：

project├── node_modules/│   ├── lib@1.0.0│   ├── lib@2.0.0│   ├── pkgA│   ├── pkgB│   └── ..├── src/└── package.json
packageA├── node_modules/│   └── lib@1.0.0├── src/└── package.json
packageB├── node_modules/│   └── lib@2.0.0├── src/└── package.json

优点：

1. 便于代码复用

2. 模块组件独立开发调试，业务理解清晰度高

3. 人员编排分工更加明确

4. 提高研发人员的公共抽取思维能力

5. 源代码访问权限设置灵活

缺点：

1. 模块划分力度不容易把握

2. 共同引用的版本问题，容易导致重复安装相同依赖的多个版本

3. 构建配置不复用，不好管理

4. 串行构建，修改模块体量大时，发布成本急剧上升

5. Code Review、Merge Request 从各自模块仓库执行，比较分散

▐  单仓多模块管理 Monorepo

随着组件/模块越来越多， multirepo 维护成本越来越大，于是我们意识到我们的方案是时候改进了。

此时目录架构大概长这样：

project├── node_modules/│   ├── lib@2.0.0│   ├── pkgA│   ├── pkgB│   └── ..├── src/└── package.json
mono-project├── node_modules/│   └── lib@2.0.0├── packages/│   ├── packageA│   │    └── package.json│   └── packageB│        └── package.json└── package.json

1. 所有源码在一个仓库内，分支管理与单体应用一样简单
2. 公共依赖显示更清晰，更方便统一公共模块版本
3. 统一的配置方案，统一的构建策略
4. 并行构建，执行效率提升
5. 保留 multirepo  的主要优势
• 代码复用
• 模块独立管理
• 分工明确，业务场景独立
• 代码耦合度降低
• 项目引入时，除去非必要组件代码
6. CR、MR 由一个仓库发布，阅读和处理十分方便

1. git 服务根据目录进行访问权限划分，仓库内全部代码开发给所有开发成员（这种非特殊限制场景不用考虑）
2. 当代码规模大到一定程度时，git 的操作速度达到瓶颈，影响 git 操作体验（中小型规模不用考虑，而且就算是 def 平台可并行量也为 500）

▐  优缺点对比梳理

总体来说，当业务发展到一定规模时，monorepo 的升级相比 multirepo 来说，是利远大于弊的。

▐  业务现状

天猫校园如意pos业务域场景丰富，整体的代码逻辑比较复杂，因此采取按照 app（项目入口）-bundle（业务域板块：可以理解为页面）-component/util（通用组件：base组件、biz组件、utils和sdk平铺，都属于这个） 的形式进行整个项目的管理。目前项目所涉及的 npm 业务模块数量已经超过了 100 个。

▐  存在的制约

1. 应用规模增长，构建依赖本地环境，构建效率低下，非业务投入成本不断上升

1. 主应用需要频繁构建

2. 构建前依赖的模块需要单独构建，构建速度串行

3. 组件还在不断增长，愈加不利于工程的维护

2. 组件类发布没有对接集团规范，无CR卡点，二级依赖凌乱

1. 代码 review 全靠 人工 diff 进行 cr

2. 每次的版本信息都是通过手动维护

3. 组件依赖的二级依赖不统一，package-conflict 非常多

▐  优化目标

构建部署发布提效，全链路CR及需求管控，全代码卡点管控，后续代码质量，单测节点补充等等

1. 降低构建部署成本，对于一次合理的多包改动，只需要进行1~2次的构建即可完成部署任务
2. 降低每次迭代的应用发布的维护成本，对于一个应用及其包含的子应用（包括集成包和微应用模式），一次完整的研发流程只需要维护一个发布迭代。发布依赖关系通过自动化流程进行优化。
3. 对于主子应用/组件可以进行合理的CR管控
4. 每个有变更的子应用都可以关联到对应的aone需求（可多个）。
5. 能将整个研发和发布流程统一到一个平台上进行操作，降低理解和操作成本。（更进一步的优化，将原来割裂的一些流程节点进行整合，以及版本迭代修改日志的统一维护。）
6. 在流程节点上可以提供扩展方式，预留后续类似代码扫码，质量评估，灰度管控等体系。

▐  选用结论

▐  落地结果

落地过程参考后面的「最佳实践」

Monorepo 只是一个管理概念，实际上它并不代表某项具体的技术，更不是所谓的框架。开发人员需要根据不同场景、不同的研发习惯，使用相应的技术手段或者工具，来达到或者完善它的整个流程，从而达到更好的开发和管理体验。

目前前端领域的 Monorepo 生态有一个很显著的特点就是只有库，而没有大一统的框架或者完整的构建系统来支持。目前的工具形态上像是传统的 CMake 那样的辅助工具，而不是像 Gradle（构建语言 + 生态链）或 Cargo（包管理器自身集成） 那样统一的方式。可能未来的趋势是像 nx 或者 turborepo 这样的库要往完整的框架发展，或者包管理器自身就逐步支持相应的功能，不需要过多的三方依赖。以下介绍一下生态中的一些核心技术：

▐  包管理方案

• Npm

npm 在 v7 才支持了 workspaces，属于终于能用上了但是并不好用的情况，重点是比较慢，通常无法兼容存量的 monorepo 应用，出来的时间太晚了，不能像 yarn 支持自定义 nohoist 以应对某些依赖被 hoist 到 monorepo root 导致的问题，也没有做到像 pnpm 以 link 的方式共享依赖，能显著的减少磁盘占用，除了 npm 自带之外没有其他优点。

• Yarn

yarn 1.x

最早支持 workspaces 模式的包管理器，配合 lerna 占据了大部分 monorepo，在比较长的一段时间里是 monorepo 的事实标准，缺点是 yarn 的共享包才会提升到 root node_modules 下，其他非共享库都会每个地方留一份，占用空间比较多，还有提升到 root 这一行为也会带来兼容性问题（有些包的 require 方式比较 hack）

yarn berry(2 ~ 3)

比较新的点就是 pnp 模式，pnp 模式是为了解决 node_modules 臃肿、复杂度过高的问题而来的，但是比较激进，所以很难支持现有的项目。不过 yarn 3 基本上把各个包管理的功能都支持了（nodeLinker 配置），从功能上可以算是最多，比较复杂，概念好多。吸收了部分竞争对手的优点，并开辟了许多有趣的功能特性。

• Pnpm

全称是 “Performant NPM”，即高性能的 npm。

如它在官方文档介绍的所说：“Saving disk space and boosting installation speed”，Pnpm 是一个能够提高安装速度、节省磁盘空间的包管理工具，并天然支持 Monorepo 的解决方案。除此之外，它也解决了很多令人诟病的问题，其中，比较经典的就是 Phantom dependencies（幻影依赖）。

pnpm 的优势：

1. 安装依赖速度快，软/硬链接结合

2. 安装过的依赖缓存全局复用，缓存逻辑基于文件块，不同版本的依赖可以只缓存 diff

3. 自身支持 workspaces 相关

推荐导读：

pnpm官网：https://pnpm.io/zh/

▐  包版本方案

• Lerna

Lerna 是一个管理工具，用于管理包含多个软件包（package）的 JavaScript 项目。它可以优化使用 git 和 npm 管理多包存储库的工作流程。Lerna 主流应用在处理版本、构建工作流以及发布包等方面都比较优秀，既兼顾版本管理，还支持全量发布和单独发布等功能。在前端领域，它是最早出现也是相当长一段时间 monorepo 方案的事实标准，具有统治地位，很多后来的工具的概念或者 workspaces 结构都借鉴了 lerna，是 lerna 的延续。在业界实践中，比较多的时间上，都是采用 Yarn 配合 lerna 组合完整的实现了 Monorepo 中项目的包管理、更新到发布的全流程。

后来停更了相当长一段时间，至今还是不支持 pnpm 的 workspaces（pnpm 下有 workspace:protocol，lerna 并没有支持），与 yarn 强绑定。

最近由 nx 的开发公司 nrwl 接手维护，不过新增的 features 都是围绕 nx 而加，nrwl 目前似乎还并没有其他方向的 bug fix 或者新增 features 的计划。不过社区也出现了 lerna-lite ，可以作为 lerna 长久停滞的补充和替代，主要的新 features 就是支持在 pnpm workspaces。

推荐导读：

1. lerna：https://www.lernajs.cn/

2. lerna-lite：https://github.com/ghiscoding/lerna-lite

• Changesets

Changesets 是一个用于 Monorepo 项目下版本以及 Changelog 文件管理的工具。在 Changesets 的工作流会将开发者分为两类人，一类是项目的维护者，还有一类为项目的开发者，开发者在Monorepo项目下进行开发，开发完成后，给对应的子项目添加一个changeset文件。项目的维护者后面会通过changeset来消耗掉这些文件并自动修改掉对应包的版本以及生成CHANGELOG文件，最后将对应的包发布出去。

▐  包构建方案

• Turborepo

上述提到传统的 Monorepo 解决方案中，项目构建时如果基于多个应用程序存在依赖构建，耗时是非常可怕的。Turborepo 的出现，正是解决 Monorepo 慢的问题。

Turborepo 是一个用于 JavaScript 和 TypeScript 代码库的高性能构建系统。通过增量构建、智能远程缓存和优化的任务调度，Turborepo 可以将构建速度提高 85% 或更多，使各种规模的团队都能够维护一个快速有效的构建系统，该系统可以随着代码库和团队的成长而扩展。

推荐导读：https://vercel.com/blog/vercel-acquires-turborepo

• Nx

定位上是  Smart, Fast and Extensible build system，出现得比较早，发展了挺久，功能特别多，基本上 cover 了各种应用场景，文档也比较详细，是现在几个 Monorepo 工具里比较接近完整的解决方案和框架的。

最近的话他们也接手了 lerna 的维护，不过给 lerna 加的东西都是围绕 nx 而来。

推荐导读：https://nx.dev/

▐  其它生态工具

• Bolt

• Preconstruct

• Rushstack

• Lage

最终我们选用了 pnpm + lerna-lite + turborepo

▐  Pnpm

pnpm 的依赖全局缓存（global store and hard link）与安装方式即是天然的依赖共享，相同版本的依赖只会安装一次，有效地节约空间以及节省安装时间，在 monorepo 场景下十分切合。

▐  Lerna-lite

pnpm 推荐的方案其实是 changesets，但是 changesets 的发版流程更贴近 Github Action Workflow，以及 打 changeset 然后 version 的概念和流程相对 lerna 会复杂一些。

不直接使用 lerna 的原因是 lerna 并不支持 pnpm 的 workspace protocol 。

同时 lerna 比较久没有更新，虽然最近被 nx 的组织 nrwl 接管了，但是 nrwl 只扩展了针对 nx + lerna 场景的功能，并没有对 lerna 的其他功能进行维护，所以社区里出现了 lerna-lite，真正意义上的延续了 lerna 的发展，目前比较有用的新功能是其 publish 命令支持了 pnpm 的 workspace protocol (workspace:)，支持了 pnpm workspace 下 lerna 的发布流程。

▐  Turborepo

如果有高速构建缓存需求则使用 turborepo。Turborepo 的基本原则是从不重新计算以前完成的工作，Turborepo 会记住你构建的内容并跳过已经计算过的内容，把每次构建的产物与日志缓存起来，下次构建时只有文件发生变动的部分才会重新构建，没有变动的直接命中缓存并重现日志。在多次构建开发时，这也就意味更少的构建耗时。

▐  前置准备

使用 pnpm 作为包管理器，全局安装 pnpm，命令如下：

$ tnpm i -g pnpm

▐  创建 mono 仓库

初始化该仓库为 mono 仓库

# 初始化成功$ tree ./your-mono-projectyour-mono-project├── packages│   ├── bundles│   │   └── bundle-a│   │       └── package.json│   └── components│       └── util-a│           └── package.json├── .gitignore├── .npmrc├── abc.json├── lerna.json├── package.json├── pnpm-workspace.yaml├── README.md└── turbo.json

Turborepo 地址：https://turborepo.org/

▐  基础 mono 配置设置

这里是使用 def 云构建 builder 配置，默认是 @ali/builder-xpos

{  "builder": "@ali/builder-xpos"}

lerna 的配置，包括 packages 的范围，publish，version 的命令配置，还有指定 npmClient 为 pnpm，这里需要使用 @lerna-lite/cli

{  "packages": [    "packages/*/*"  ],  "command": {    "publish": {      "conventionalCommits": true,    },    "version": {      "conventionalCommits": true,      "syncWorkspaceLock": true    }  },  "version": "independent",  "npmClient": "pnpm"}