详解 Monorepo：优势、挑战与最佳实践

您正在进行一个项目。前端在一个仓库，后端在另一个，共享库在第三个。您不断切换仓库，还得祈祷版本不要彼此偏离。

现在想象一下，一切都在同一个地方。一个仓库容纳您所有的项目，共享代码即时更新，改动通过一次提交就能贯通全局。

Monorepo 能让这一切成真。这也是为什么许多大型科技公司也在使用它，例如：

• Google 构建了 Piper 并进行大规模自动化
• Meta 扩展了 Mercurial
• Microsoft 以 Git monorepo 运行 Windows，并配合 VFS for Git
• Uber 甚至从单仓＞多仓＞在工具追上后又回到单仓

在本指南中，您将了解什么是 monorepo、它与 polyrepo 的对比，以及您应了解的关键优势、挑战与最佳实践。

什么是 Monorepo？

Monorepo（单体代码库）指的是一个仓库。在 monorepo 中，您所有不同的项目都位于同一处，而不是分散在各个独立的仓库中。

即使项目彼此并列，它们依然是独立的。也就是说，您可以独立构建、测试和部署它们，同时还能享受把一切集中在一起的便利。

但需注意，单体应用与 monorepo 并不是一回事：

• 单体应用（monolith）是一个作为单一整体构建并运行的软件应用，通常在同一数据集上工作。它可以位于 monorepo 内（作为众多项目之一）。
• Monorepo 以一种方式存储和管理代码，让多个项目共处同一仓库，但彼此仍然独立。

Monorepo 不是单体应用。事实上，monorepo 往往与微服务非常契合，因为每个服务都能在同一仓库中存在，同时保持独立。

Monorepo 的概念并不新鲜。

在 2000 年代早期，大型科技公司开始采用“共享代码库”的方式。理念很简单：与其把代码散落在众多仓库里，不如集中到一处，便于协作。

自那以后，像 Google、Meta、Microsoft、Airbnb、Twitter（X）、Uber 和 Pinterest 等大型科技公司都采用 monorepo 来管理其庞大且快速迭代的代码库。

Monorepo 与 Polyrepo

与 monorepo 相对的是 polyrepo（多仓）。让我们看看它们有何不同。

Polyrepo

Polyrepo，也称 multirepo，指每个项目都有各自独立的仓库。

例如，前端代码可能在一个仓库，后端在另一个，而共享库则各自独立。每个仓库独立管理其依赖与工作流。

Monorepo 与 polyrepo 对比。图片由作者提供。

快速浏览关键差异

让我们看看 monorepo 与 polyrepo 的关键区别：

Monorepo 的优势

Monorepo 带来诸多益处。以下是其中一些：

更好的协作与可见性

当所有代码都在一处，每个人都能清楚看到进展。您可以查看其他项目、从中学习，或在需要时伸出援手。

这让团队配合更顺畅，促进跨团队协作，并减少信息孤岛。

简化依赖管理

如果不同项目使用同一库却各自维护版本，事情会很快变得混乱。

例如，一个项目使用旧版，另一个使用新版。这会让代码更难运行，您可能得在多个地方重复修复同一问题。

而在 monorepo 中，共享代码位于单一位置。您更新一次，所有项目立刻获得修复。无需四处追查版本不一致，也不用处理版本冲突。

原子化提交与更易重构

有时您需要做的改动会影响多个项目。例如，您可能想更新一个共享库。在 monorepo 中，您可以更新这段代码，并在一次提交中将修复应用到所有项目。

这意味着所有项目保持同步，您不必担心误伤其他代码。

一致的工具与流程

一个仓库，就有一套统一的构建、测试与部署方式。无需为不同项目记住不同的配置。这也让新成员更容易无障碍上手。

特定工作流中的更快迭代

如果两个或更多项目依赖同一段代码，例如共享库或工具，您不必在独立仓库里逐个更新各个项目。

在 monorepo 中，您只需更新一次代码，仓库内的所有项目都会立即获得变更。也就是说，您无需在多个仓库间来回切换，而是在一处修改，处处生效。

这在一些日常场景中特别有用：

• 当您重构共享代码时，更新库后，所有依赖它的服务都会立即获得更新。
• 当您发布一个涉及多个应用的功能时，可以一起发版，而无需在不同仓库间反复协调。
• 连 CI/CD 流水线也更简单，因为构建和测试都针对同一代码库，而不是被重复执行。

这些都能减少反复沟通、降低上下文切换，缩短反馈回路，从而在不增加额外负担的情况下加快迭代。

Monorepo 的挑战

Monorepo 带来很多好处，同时也伴随一些挑战。以下是主要问题：

可扩展性与性能问题

随着仓库变大，诸如克隆、搜索，甚至在编辑器中打开这样的日常操作都会变慢。为什么？因为 Git 最初并非为处理海量代码库而构建。因此大公司往往会感受到压力。

更长的构建与测试时间

由于所有项目都在同一处，哪怕是一个小改动也可能为 CI/CD 流水线带来大量额外工作。因此，开发者常常需要等待构建或测试套件完成，才能合并或发布代码。

随着时间推移，这些延迟会引发更多问题，比如阻塞其他工作，使得实施小而频繁的改动更加困难。

以 Uber 为例：当他们的 Go monorepo 达到数百万行代码时，一些工程师在合并前需要等待数小时以完成构建与验证。

一段时间后，他们通过 Bazel 和自定义构建队列等工具加速流程。但这也凸显出：当所有项目共享一个仓库时，CI 很快就会成为瓶颈。

主分支被破坏的风险

主分支是 Git 中默认的分支，承载着您代码的最新稳定版本。在 monorepo 中，所有人都在这个共享分支上工作，因此只要有一次改动把它搞崩，整个团队（甚至公司）都可能被阻塞，直到修复完成。

以 Airbnb 为例。他们曾实行“民主化部署”（任何工程师都可测试并直接投产，无需等待发布经理）。

起初这感觉很快，但随着公司成长，管理一切变得困难，因为他们的代码都存放在一个庞大的单一仓库中。团队成员同时将改动投入生产，更新相互冲突，导致问题原因难以定位。

访问控制与安全

在 monorepo 中限制访问很难，因为所有代码、配置文件、构建脚本和其他资源都集中存放。默认情况下，只要开发者有仓库访问权限，通常就能查看并修改这些组件。

这对于开放协作没问题，但当某些部分（如安全密钥、部署脚本或专有算法）需要更严格的权限时，就会成为挑战。

例如，一家公司可能把其网站代码保存在同一个 monorepo 中。负责网站的开发者并不一定需要访问生产服务器凭据，但由于一切共处一处，要完全避免他们意外查看或编辑这些敏感文件可能很难。

新开发者的学习曲线

对于新成员来说，一个包含大量项目的庞大仓库可能令人不知所措。因为文件和文件夹太多，他们很难知道从何入手，或者哪些与自己的工作相关。

他们还需要先了解项目结构、工具和依赖，才能自信地进行构建或更改，这会在熟悉一切之前放慢他们的进度。

Monorepo 管理最佳实践

为确保 monorepo 顺畅运行，您应做到以下几点：

• 以合理的方式组织仓库。将相关项目放在一起，使用清晰命名，让任何人都能轻松找到所需内容。
• 避免长期存在的分支。尝试基于主干的开发，大家频繁将更改合入主分支。这能保持仓库整洁并减少冲突。
• 将依赖固定到特定版本，确保所有人保持同步。一次性在全仓升级它们以避免不一致。
• 使用现代构建工具，如 Bazel、Buck、Nx、Pants、Rush 或 Lerna 来加快构建并处理大型仓库的复杂性。
• 若仅有小部分变更，不要重建或重测整个仓库。使用差异化构建与定向测试来节省时间，并为开发者提供更快的反馈。
• 在您的 VCS 平台（如 GitHub/GitLab）中设置 Git CODEOWNERS，以保护部署脚本或配置文件等敏感区域，并要求对应团队审核变更。

常用的 Monorepo 管理工具

随着项目扩张，monorepo 可能变得复杂。为简化管理，许多工具被用来辅助构建、依赖与组织维护。

以下是一些最常见的工具：

Bazel

Bazel 是由 Google 创建的开源构建系统，用于处理非常庞大且复杂的代码库。

其关键特性包括：

• 快速构建：借助高级缓存、优化的依赖分析与并行执行，仅重建发生变化的部分。
• 多语言支持：跨平台与多语言工作，包括 Java、C++、Go、Android 和 iOS，并支持 Windows、macOS、Linux。
• 易于扩展：既能处理庞大的 monorepo，也支持多仓场景，适用于各种规模的组织。
• 可扩展性：通过其扩展系统可新增语言与平台，并有不断壮大的社区支持。

Google、Stripe 和 Dropbox 等公司都信任 Bazel 来构建与测试关键基础设施和应用。

Nx

Nx 是用于管理 monorepo 的开源工具包，尤其在 JavaScript 和 TypeScript 领域广受欢迎，对 React、Angular、Vue、NestJS 等框架有强力支持。它帮助团队在同一处组织多个应用与库，同时保持构建与测试的高效。

其关键特性包括：

• 智能任务运行器：理解代码各部分之间的依赖关系，仅运行必要任务，避免浪费时间。
• 兼容现有环境：可运行现有脚本，如 npm 或 Gradle 任务，无需更改您的配置。
• Nx Cloud：通过远程缓存、更快的 CI 运行，以及自动检测并修复问题的工具，加速开发生命周期。
• 配套工具：如 Nx Console，提供自动补全、可视化项目图与便捷的任务管理方式。

Lerna

Lerna 是最早且最受信赖的 JavaScript/TypeScript monorepo 管理工具之一。它让在单一仓库中组织多个包变得容易，并辅助构建、测试与发布。

事实上，一些知名项目，如 Create React App、Jest 与 NestJS，都使用 Lerna 来管理其包。

其关键特性包括：

• 智能构建：通过复用缓存结果避免重复工作，而非反复重建相同代码。
• 快速执行：任务并行运行，同时遵循依赖顺序。
• 分布式缓存：构建结果可在开发者与 CI 系统之间共享，缩短构建时间。
• 包发布：简化发布到 npm，支持统一版本与独立版本两种模式。
• 扩展能力：可将工作负载分布到多台机器，无需额外设置。
• 可视化：内置工具展示仓库中项目与依赖的关系。
• 低门槛配置：所需配置很少，您可以保留现有 npm 脚本并让其运行更快。

Pants

Pants 是一款快速且易用的构建系统，适用于各种规模的 monorepo。它最初专注于 Python，如今也支持 Go、Java、Scala、Kotlin、Shell 和 Docker，并在持续增加更多语言支持。

因此它被 Coinbase、IBM、Slack、Salesforce 与 Orca Security 等公司，以及众多小团队广泛使用与信任。

其关键特性包括：

• 易于采用：所需配置最小化，能自动推断大部分构建信息，减少模板化样板维护。
• 安全构建：支持多重依赖解析与锁定文件，打造可复现的构建，更能抵御供应链攻击。
• 灵活性：以文件级粒度工作，能在不强制严格模块化的情况下处理复杂或纠缠的依赖结构。
• 可扩展性：通过 Python 的插件系统，团队可按需自定义。
• 感知 Git：检测分支间变更，仅运行受影响的测试或构建。

Rush

Rush 是为需要在单一仓库中管理多个包的 JavaScript 项目设计的 monorepo 工具。

其关键特性包括：

• 为规模而生：支持并行、增量与分布式构建，即便超大仓库也能保持高效。

• 团队协作：保持依赖版本一致，在引入新包前进行审查，支持统一与独立版本管理。
• 可靠安装：支持 pnpm（推荐）、npm 和 Yarn，确保可预测的安装过程。
• 一体化工具：在一处处理安装、链接、构建、发布、版本管理与变更日志。

Rush 是开源且受信任的平台，被 Azure SDK、HBO Max、OneDrive、SharePoint、Office 365 和 Wix 等重大产品采用。

Turborepo

Turborepo 是一款高性能构建系统，让 JavaScript 和 TypeScript 的 monorepo 更快、更易管理。它专注于解决同一仓库内并存多个应用与包时常见的扩展问题。

其关键特性包括：

• 远程缓存：保存构建与测试结果，避免重复执行相同工作，缩短 CI 时间。
• 任务调度：以正确顺序并行运行任务，充分利用所有可用内核以获得最大速度。
• 渐进式采用：可在数分钟内接入任意仓库，复用现有 package.json 脚本，并与 npm、Yarn 或 PNPM 协同工作。
• 轻量克隆：允许开发者仅克隆所需的 monorepo 部分，减少环境搭建时间。
• 优化工作流：只构建发生变化的部分，保持快速的反馈回路。
• 熟悉的开发体验：兼容标准 Git 工作流，无需改变团队既有的代码管理方式。

Moon

Moon 是用 Rust 编写的高速 monorepo 管理工具。它支持 JavaScript、TypeScript、Rust、Go 和 Ruby 等语言。

其关键特性包括：

• 速度：利用智能缓存与增量构建，仅重建发生变化的代码。
• 协作：远程缓存可在团队成员与 CI 之间共享结果。
• 跨平台：可在 Linux、macOS 与 Windows 上运行。
• 项目图谱：映射依赖关系，帮助组织与扩展大型仓库。

Lage

Lage 是为 monorepo 打造的任务运行器，专注速度与效率。它帮助团队避免重复构建已完成的工作。

其关键特性包括：

• 跳过重复工作：本地或复用团队成员的结果，避免重复构建。
• 快速配置：易于配置并可跨环境工作。
• 缓存：支持本地缓存或外部存储，加速 CI 流水线。
• 洞察：包含分析构建与可视化依赖图的工具。

Yarn workspaces

Yarn 引入了 workspaces，以便更轻松地管理在单一仓库（monorepo）中包含多个包的项目。

其关键特性包括：

• 不重复安装：公共依赖仅在根目录安装一次，避免每个包的 node_modules 膨胀。
• 自动链接：若一个包依赖同仓库内的另一个包，Yarn 会为您自动完成链接。
• 单一锁文件：为整个仓库维护一个 yarn.lock，使所有包的版本保持一致。

何时使用 Monorepo

来看几个常见场景，帮助您判断 monorepo 是否适合：

小到中型团队且代码共享较多

如果您的团队较小，且多个项目之间复用大量代码，monorepo 能为您节省时间。因为团队所有人都在同一处工作，共享库能不费力地保持同步，可谓双赢。

依赖关系紧密的项目

当不同项目之间依赖紧密时，把它们放在同一仓库。这样，改动可以在一次提交中一并完成，而无需在多个仓库间周旋。

寻求统一工具与可见性的组织

使用 monorepo，您可以设置统一的 CI/CD 配置。这并不意味着所有项目只用一条流水线，而是可以优化流水线，使其仅运行受近期代码更改影响的构建与测试，从而节省时间与资源。

但 monorepo 并非万金油。如果您的项目完全彼此独立，或需要严格的访问控制（某些团队不应看到特定代码），那么 polyrepo（多个仓库）可能更适合。

权衡利弊

以下是 monorepo 的优势与劣势的快速概览：

总结

Monorepo 能让协作更顺畅、依赖更简单、迭代更快速，但也确实在规模、性能与访问控制方面带来挑战。是否采用，应基于团队结构、项目间依赖紧密度，以及您是否准备好投入合适的工具来做出战略性选择。

但若没有良好的协作习惯与清晰的所有权划分，即便最好的 monorepo 设置也会举步维艰。如果您正探索这条路径，值得先夯实基础。 Software Engineering Principles in Python 课程是一个很好的起点。它将帮助您建立让 monorepo 获得成功的实践方法。