技能介绍

从 Polyrepo 到 Monorepo 的迁移痛点

当你的项目从最初的几个包膨胀到十几个仓库时，polyrepo 的边际成本开始显现：跨仓库的公共依赖重复安装、一次类型定义变更需要遍历所有相关仓库重新构建、代码评审时 PR diff 散落在多个仓库难以追踪。尤其是在 CI 层面，哪怕只是修改了一个共享工具包，所有依赖它的仓库都会触发完整的构建流水线，等待时间随着仓库数量线性增长。

技能如何工作

这套技能围绕 Turborepo + pnpm workspaces 的标准化方案展开，核心能力分为五步。

项目结构设计：按 apps + packages 的约定划分目录，让应用层与可复用的库层各归其位。

包管理与引用：通过 pnpm-workspace.yaml 统一声明工作空间，包间引用使用 workspace:*，发布时自动替换为实际版本号，避免手动维护版本依赖的出错风险。

任务编排：在 turbo.json 的 pipeline 中定义任务依赖关系：

^ 表示拓扑排序——先构建被当前包依赖的包再构建自身
$ 表示仅依赖当前包自身完成

缓存策略：本地缓存通过 turbo run build 自动记录 outputs 目录下的产物，相同输入直接从缓存还原；远程缓存借助 --team= 参数配合 Vercel Remote Cache 实现团队成员共享。缓存指纹基于包名、package.json、lockfile、源码内容和环境变量自动失效，也可以通过 inputs 字段精细控制。

增量构建与 CI 优化：--filter=./apps/web... 只构建变更包及其依赖，--since=origin/main 只构建相对于主分支有变更的内容，--dry-run 预览执行计划而不实际运行。CI 侧建议缓存 node_modules/.cache/turbo 目录，让构建缓存跨流水线复用。

适用边界与注意点

并非所有项目都适合引入 Monorepo。如果项目只有 2-3 个小包，构建工具和工作空间管理的 overhead 会超过它带来的收益。同样，以非 JavaScript/TypeScript 为主的项目虽然 Turborepo 也部分支持，但并非最佳选择。在迁移前，建议先评估仓库数量、共享代码比例和 CI 等待时间的当前痛点，再决定是否采用这套方案。