演进为 Monorepo

演进为 Monorepo

这篇笔记还在编辑中，内容可能会继续补充、调整或重写。

本阶段目标

当应用、组件库和共享配置已经存在真实的原子变更需求时，再迁移到 Workspace。Monorepo 解决协同和一致性问题，也会引入任务编排、权限和发布治理成本。

目标结构

frontend-lab/
├── apps/
│   └── web/
├── packages/
│   ├── ui/
│   ├── eslint-config/
│   ├── tsconfig/
│   └── shared/
├── pnpm-workspace.yaml
└── package.json

内部依赖使用 workspace: 协议，包只通过公共入口互相引用。使用依赖边界规则阻止应用反向被共享包依赖，或跨包导入另一个包的私有源码。

声明任务图

对 build、test、lint 和 typecheck 显式声明：

  • 依赖的上游任务
  • 输入源码、配置和环境变量
  • 输出目录和报告
  • 是否允许并行
  • 是否适合缓存

缓存键必须包含影响结果的工具版本、配置和环境。缓存命中快但结果错误，比完全没有缓存更危险。

渐进迁移

  1. 先移动共享配置，保持应用构建不变。
  2. 再移动纯工具包和组件库。
  3. 为每一步保留独立提交并执行完整测试。
  4. 最后引入任务编排和远程缓存，先观察命中率再优化。

故障演练

  1. 故意遗漏一个环境变量输入，观察缓存是否返回过期结果。
  2. 制造包之间的循环依赖，验证边界检查能否阻止。
  3. 修改 UI 包，确认只执行受影响应用和必要上游任务。

验收标准

  • 根目录一次冻结安装即可恢复完整工作区
  • 包依赖和任务依赖都能可视化或查询
  • 私有源码跨包导入会被自动检查阻止
  • 变更影响分析不会漏掉真实消费者
  • 关闭缓存后仍能得到相同构建与测试结果

下一篇：沉淀脚手架与工程平台。