monorepo-navigator

Monorepo Navigator

Tier: POWERFUL
Category: Engineering
Domain: Monorepo Architecture / Build Systems

---

概述

管理和优化 Monorepo。涵盖 Turborepo、Nx、pnpm workspaces 和 Lerna。支持跨包影响分析、仅针对受影响包的选择性构建与测试、远程缓存、依赖图可视化，以及从多仓库到 Monorepo 的结构化迁移。包含面向工作区感知开发的 Claude Code 配置。

---

核心能力

• 跨包影响分析 — 判断共享包变更时哪些应用会受到影响
• 选择性命令 — 仅对受影响的包运行测试/构建（而非全部）
• 依赖图 — 以 Mermaid 图表可视化包之间的关系
• 构建优化 — 远程缓存、增量构建、并行执行
• 迁移 — 分步将多仓库迁移为 Monorepo，且不丢失历史记录
• 发布 — 使用 changesets 进行版本管理、预发布渠道、npm 发布工作流
• Claude Code 配置 — 工作区感知的 CLAUDE.md，包含按包划分的说明

---

适用场景

适用于：

• 多个包/应用共享代码（UI 组件、工具函数、类型、API 客户端）
• 因任何改动都会导致全部重新构建，构建时间过长
• 从多个仓库迁移到单一仓库
• 需要以协调的版本号向 npm 发布包
• 团队跨多个包协作，需要统一的工具链

不适用于：

• 没有共享包的单应用项目
• 团队/项目边界完全独立（多仓库即可）
• 共享代码很少，复制粘贴的开销可以接受

---

工具选型

工具	最适合	核心特性
Turborepo	JS/TS Monorepo，流水线配置简单	一流的远程缓存，配置极简
Nx	大型企业，插件生态	项目图、代码生成、受影响命令
pnpm workspaces	工作区协议，磁盘效率	使用 workspace:* 引用本地包
Lerna	npm 发布、版本管理	批量发布，约定式提交
Changesets	现代版本管理（优先于 Lerna）	生成变更日志，预发布渠道

目前大多数现代方案：pnpm workspaces + Turborepo + Changesets

---

Turborepo

→ 详情参见 references/monorepo-tooling-reference.md

工作区分析器

python3 scripts/monorepo_analyzer.py /path/to/monorepo
python3 scripts/monorepo_analyzer.py /path/to/monorepo --json

常见架构与 CI 模式另见 references/monorepo-patterns.md。

常见陷阱

陷阱	解决方法
每个 PR 都运行不带 --filter 的 turbo run build	CI 中始终使用 --filter=...[origin/main]
workspace:* 引用导致发布失败	使用 pnpm changeset publish，它会自动将 workspace:* 替换为真实版本号
无关文件变更导致所有包重新构建	在 turbo.json 中调整 inputs，将文档、配置文件排除在缓存键之外
共享 tsconfig 导致一个包破坏所有类型检查	正确使用 extends：每个包继承根配置，但覆盖 rootDir / outDir
迁移过程中丢失 git 历史	合并前使用 git filter-repo --to-subdirectory-filter，切勿手动移动文件
CI 中远程缓存不生效	检查 TURBO_TOKEN 和 TURBO_TEAM 环境变量；使用 turbo run build --summarize 验证
CLAUDE.md 过于笼统，Claude 修改了错误的包	在每个包的 CLAUDE.md 中添加明确规则，如"处理 X 时，只修改 apps/X 中的文件"

---

最佳实践

1. 根目录的 CLAUDE.md 定义整体结构：记录每个包、其用途以及依赖规则
2. 每个包的 CLAUDE.md 定义具体规则：说明允许与禁止的内容，以及测试命令
3. 始终用 --filter 限定命令范围：每次改动都运行全部任务，就违背了初衷
4. 远程缓存不可或缺：没有它，单体仓库的 CI 会比多仓库的 CI 更慢
5. 优先使用 Changesets，而非手动版本管理：在单体仓库中，切勿手动修改 package.json 中的版本号
6. 共享配置放在根目录，由各包继承扩展：tsconfig.base.json、.eslintrc.base.js、jest.base.config.js
7. 合并共享包改动前进行影响分析：运行受影响范围检查，并告知影响范围
8. 保持 packages/types 为纯 TypeScript：不含运行时代码，无依赖，构建和类型检查都更快