monorepo 是什么

要点

  • 项目刚起步时，一个前端应用、一个后端服务、几个脚本，随便放一个仓库里就能跑
  • monorepo 不是某个工具，也不是某个框架
  • 刚接触这个话题时，大家容易先想到 Git 层面：仓库会不会太大、提交记录会不会太乱、权限会不会太复杂
  • 小型静态站点未必需要 monorepo
  • 这里容易有误解：以为 monorepo 就是"所有项目丢进同一个仓库"，目录随便堆

内容

1. 项目一变大，仓库结构就开始拧巴

项目刚起步时，一个前端应用、一个后端服务、几个脚本，随便放一个仓库里就能跑。

这阶段谁也不会认真想仓库结构。

问题出在项目往前发展的时候。

以 AI 应用为例。最早可能只有一个 Web 页面，后来加了 API 服务、异步 worker、共享 UI、共享类型、共享提示词、共享配置。再往后，文档站、playground、后台管理也跟着冒出来。

这时候你不是写不出来，而是改一处要追好多地方。前端加个字段，后端要跟，worker 也要认，文档里的示例还要同步。仓库一旦分散开，一个本该一次解决的改动就会拖成好几轮。

多数人第一次认真思考 monorepo，就是在这个时候

2. monorepo 就是把多个项目放回同一个仓库

不要把这个词想复杂。

monorepo 不是某个工具，也不是某个框架。它就是一种仓库组织方式：把原本分散在多个仓库里的多个项目，放回同一个仓库里管理。

NOTE

仓库指的是 git 仓库

这里说的"多个项目"，可以是各种组合：

  • 一个 Web 应用 + 一个 API 服务
  • 一个移动端 + 一个后台管理
  • 多个前端应用 + 一批共享包
  • 应用、组件库、脚本工具、文档站全放一起

所以 monorepo 最先解决的不是构建速度，而是代码关系——哪些东西本来就该一起改，哪些共享逻辑本来就不该靠复制粘贴维持。monorepo 只是把这件事在仓库层面落了下来。

3. 多仓库真正难受的地方不在 Git

刚接触这个话题时，大家容易先想到 Git 层面：仓库会不会太大、提交记录会不会太乱、权限会不会太复杂。

这些是真问题，但不是日常开发里最痛的。

真正拖慢你的是这些：

  • 共享类型要手动同步，改了一边忘了另一边
  • 一个接口改完，要等多个仓库分别发版才能联调
  • 本地调试要同时开好几个项目，还得对齐版本
  • 明明是一件事，却变成好几个仓库里的好几次提交

仓库拆开以后，团队并没有更轻松——只是把一处该解决的问题分散到了好几个地方。

4. AI 应用碰到这个问题会更早

小型静态站点未必需要 monorepo。但 AI 应用天然会发展出很多层，而且这些层的关系很紧。

一套典型系统跑一段时间以后，目录大概是这样：

apps 独立运行的应用

web 用户直接访问的 Web 应用

admin 后台管理

api 接口服务

worker 任务和异步处理

packages 跨应用共享的代码

ui 共享组件

shared 共享类型和工具

prompts 共享提示词和模板

config 共享配置 重点不是目录整齐，而是这些东西本来就在一起工作。前端用共享组件和类型，API 的数据结构要和页面对齐，worker 的 AI 任务和应用层共用一套 schema，提示词模板和配置也不是只属于某一个 app。

拆散它们，协作成本马上就上来。

5. monorepo 不是把代码都塞进一个文件夹

这里容易有误解：以为 monorepo 就是"所有项目丢进同一个仓库"，目录随便堆。

不是。monorepo 真正有价值的地方，在于把边界重新摆清楚：

  • 哪些是独立应用
  • 哪些是共享包
  • 哪些配置应该统一
  • 哪些代码只该待在自己的业务里

monorepo 不是取消边界，而是把边界收回一个地方，重新整理一遍。

Canvas actions64%Exit zen mode

Drawing canvas 图里最值得注意的不是仓库数量变少了，而是共享那一层终于不用在多个仓库之间来回拷贝同步了。

6. 这件事背后要回答的几个问题

多数团队不是一开始就选 monorepo，而是做到中途发现继续拆着维护太累，才回头重构。

当你的项目开始同时出现这些信号：

  • 一个需求要改前端、后端和共享类型
  • 一个修复要同时动多个应用
  • 一个基础能力开始被很多地方复用
  • 一个版本升级会牵到很多子项目

那这些内容放在多个仓库里，就不是"解耦"，而是把本来紧密的关系硬拆开了。

这也引出了 monorepo 后续要解决的核心问题：

  • 同一个仓库里的多个项目怎么互相引用
  • 共享代码该放在哪
  • 什么该进 apps，什么该进 packages
  • Turborepo 在这里负责什么
  • 项目多起来以后，开发、构建、缓存怎么串

这一章不会一上来堆工具命令，而是先把这些问题一层一层拆开。先把 monorepo 讲明白，后面再讲 workspace、Turborepo、共享包和任务编排。

7. 总结

monorepo 回答的是一个很实际的问题：当几个项目本来就在一起演进时，仓库要不要继续分散放着。

对 AI 应用来说，这个问题来得更早。前端、后端、worker、共享 schema、共享 UI、共享提示词，这些东西越长越紧，分散维护的成本会越来越高。

下一篇先把最容易混的几个词分开：monorepo、workspace、Turborepo 各自在做什么。