Monorepo

背景与问题界定 随着前端项目规模的扩大，monorepo 已经成为中大型项目的标准组织方式。pnpm workspace + TypeScript + turborepo 的组合方案逐渐成为主流技术栈。但在 monorepo 中使用 TypeScript 面临着几个特有的挑战：首先是类型共享问题——公共类型定义放在哪个包中？如何在保持类型一致性的同时避免循环依赖？其次是构建性能——在包含 20+ 子包的项目中，全量类型检查耗时可达 30 秒以上，极大地影响了开发体验和 CI 流水线效率。再者是发布约束——当 A 包的类型定义引用了 B 包，A 的发布版本如何与 B 的版本保持一致？这些问题如果不在工程化层面系统性解决，monorepo 带来的类型一致性红利很快会被构建和发布摩擦抵消。 目标拆解与工程约束 类型包的独立版本管理：通用类型定义放在独立的 @company/types 包中，遵守 semver，变更时通过 changesets 自动生成 changelog。 增量编译替代全量编译：使用 TypeScript 的 Project References 或 tsc --build 实现依赖感知的增量编译，大幅减少全量检查的场景。 类型可见性控制：包的 package.json 的 types 字段只暴露公共类型，内部类型通过 tsconfig.json 的 paths 映射避免被外部引用。 构建管道的缓存优化：结合 turborepo 的缓存策略，未变更包的编译产物直接复用缓存，CI 构建时间控制在 3 分钟以内。 方案设计 类型共享架构 在 monorepo 中，类型共享有三种模式：集中式类型包、分布式内联类型 和 接口契约生成。我们推荐集中式类型包作为默认方案。 集中式类型包 ( packages/types ) 放置所有跨包共享的类型定义，包括 API 请求/响应 DTO、配置接口、事件定义和常量枚举。其他包通过 @company/types 导入。这种模式的优点是类型定义单一来源，不存在多个副本的同步问题。缺点是可能演进为巨大的类型垃圾场，需要通过子域拆分和定期清理来控制： ...

背景 这类问题在真实项目里很常见：高并发、复杂依赖、发布频繁、团队协作面广。只有把边界条件提前定义清楚，系统才会在压力下保持稳定。 实践要点 先定义目标：可用性、延迟、成本哪个优先。 把关键路径显式化：超时、重试、降级、回滚。 把策略写进代码和流程，而不是只停留在文档。 代码片段 const state = reactive({ loading: false }) 总结 工程实践最怕“看起来正确”。把策略做成可观测、可验证、可回滚的闭环，才能在生产环境里真正稳定运行。 稳定性不是某个技巧，而是持续的系统化约束。

背景 Monorepo 常见痛点是：改了一个子目录，多个镜像都触发重建。 改进方向 精细化 .dockerignore 子项目独立 context 共享基础层分离 COPY services/api/go.mod services/api/go.sum ./ RUN go mod download COPY services/api/ ./ RUN go build -o app ./cmd/api 总结 缓存命中率是 CI 成本的核心变量，Monorepo 必须做分层构建设计。 构建系统的复杂度，迟早会和代码规模一起增长。