monorepo-setup-checklist

汇总「Monorepo 搭建」中最容易踩的坑与必做项，提供一份可勾选清单，助你一次做对、避免返工。 ✅ 可勾选清单： 【项目结构】 - [ ] 明确划分 packages 目录结构（如 apps/、packages/） - [ ] 统一包命名规范（如 @scope/package-name） - [ ] 避免循环依赖，确保依赖关系清晰 【工具选型】 - [ ] 选择合适的 Monorepo 管理工具（如 pnpm workspace、Turborepo、Nx、Lerna） - [ ] 配置统一的包管理器（推荐 pnpm） - [ ] 启用 workspace 协议（workspace:*）管理内部依赖 【依赖管理】 - [ ] 区分 dependencies、devDependencies 和 peerDependencies - [ ] 避免重复安装相同依赖，利用 workspace 提升效率 - [ ] 定期执行依赖审计（audit）和更新 【构建与缓存】 - [ ] 配置增量构建与任务缓存（如 Turborepo cache） - [ ] 设置构建顺序，确保依赖包先构建 - [ ] 支持并行构建以提升效率 【脚本管理】 - [ ] 统一 scripts 命令命名（如 dev、build、test） - [ ] 使用 workspace 命令批量执行脚本（如 pnpm -r run build） - [ ] 为根目录和子包分别配置合理脚本 【版本与发布】 - [ ] 确定版本策略：独立版本（independent）或统一版本（fixed） - [ ] 配置自动化发布流程（如 changesets、lerna version） - [ ] 自动生成变更日志（CHANGELOG） 【测试】 - [ ] 配置跨包测试环境 - [ ] 支持按需运行受影响测试（affected tests） - [ ] 集成 CI/CD 中的测试流程 【代码规范】 - [ ] 统一 ESLint、Prettier 配置并继承至各子包 - [ ] 配置 TypeScript 路径映射（path mapping） - [ ] 启用严格类型检查 【CI/CD】 - [ ] 配置仅构建和测试受影响的项目 - [ ] 缓存 node_modules 和构建产物以加速流水线 - [ ] 支持多环境部署（dev/staging/prod） 【文档】 - [ ] 编写 Monorepo 使用指南（含开发流程、发布流程） - [ ] 记录常见问题与解决方案 - [ ] 提供新成员上手文档 【监控与维护】 - [ ] 定期检查依赖冲突与版本漂移 - [ ] 监控构建性能，优化慢任务 - [ ] 定期清理无用包和代码 ⚠️ 常见坑点提醒： - 忽视依赖提升导致安装失败或版本冲突 - 未配置缓存导致 CI/CD 构建缓慢 - 内部包未正确声明 peerDependencies 引发布署问题 - 忽略 TypeScript 路径映射导致 IDE 支持异常 - 发布流程未自动化，手动操作易出错 完成以上 checklist，助你高效搭建稳定可维护的 Monorepo 项目。

存档时间线

版本索引永久保留；内容副本只保留最新 1 份，更早版本仅留索引与哈希（存档时间线的证据链不会因此断裂）。

下载存档内容副本