1. 为什么需要TypeScript monorepo约定在大型前端项目中随着代码量增长和团队规模扩大传统的多仓库multirepo管理方式会带来诸多痛点。我经历过一个典型场景某个公共工具库需要同时被三个前端项目使用每次修改工具库都要手动同步到各个项目版本管理变成噩梦。而monorepo通过单一仓库管理多个项目/包配合TypeScript的类型系统能从根本上解决这类问题。但monorepo不是银弹。去年我们迁移到monorepo架构时前两个月几乎每周都会出现构建失败、类型冲突或依赖混乱的问题。经过半年实战我们总结出十条核心约定这些规则让团队开发效率提升了40%构建时间减少65%。下面分享这些用血泪教训换来的经验。2. 项目结构与workspace配置2.1 标准化目录结构我们的monorepo采用如下结构关键部分monorepo/ ├── packages/ │ ├── libs/ # 公共库 │ │ ├── utils/ # 基础工具 │ │ └── ui/ # UI组件库 │ └── apps/ # 应用目录 │ ├── web/ # 主Web应用 │ └── admin/ # 后台管理系统 ├── package.json └── tsconfig.json # 根级配置重要提示避免过度嵌套我们曾尝试按业务域划分目录结果导致导入路径变得冗长如monorepo/domainA/subDomainB/moduleC后来简化为现在的两层结构。2.2 workspace配置要点根目录package.json关键配置{ private: true, workspaces: [ packages/libs/*, packages/apps/* ], scripts: { clean: rimraf **/{dist,node_modules}, build: turbo run build, type-check: tsc --build --force } }踩坑记录必须设置private: true否则npm/yarn会拒绝安装workspace通配符匹配要明确我们曾因漏写apps/*导致部分包未正确链接使用Turborepo时turbo.json中要正确配置pipeline后面会详述3. TypeScript配置策略3.1 分层tsconfig架构我们采用三级配置方案根级tsconfig.base.json- 共享配置子项目tsconfig.json- 继承并扩展子项目tsconfig.build.json- 构建专用示例根配置{ compilerOptions: { target: ES2020, module: ESNext, strict: true, skipLibCheck: true, forceConsistentCasingInFileNames: true, moduleResolution: NodeNext, paths: { libs/*: [packages/libs/*/src], apps/*: [packages/apps/*/src] } }, exclude: [**/node_modules] }特别注意TypeScript 7.0将废弃baseUrl我们已提前迁移到pathsmoduleResolution: NodeNext方案。如果你的项目还在用baseUrl现在就该开始改造了。3.2 类型隔离与共享我们制定了三条铁律业务逻辑类型必须放在对应的包内跨包共享类型需提取到types专用包禁止直接导入其他包的*.d.ts文件曾经因为违反第三条导致一个类型定义被不同包重复声明引发难以调试的类型冲突。现在通过types集中管理问题彻底解决。4. 依赖管理规范4.1 版本控制策略所有内部包必须使用workspace:*协议{ dependencies: { libs/utils: workspace:*, lodash: ^4.17.21 } }外部依赖管理要点主要依赖如React、Vue在根package.json声明统一版本特殊版本需求需团队审批每周执行npm outdated检查更新4.2 循环依赖检测我们通过以下脚本检测循环引用npx madge --circular --extensions ts,tsx packages/将检测结果加入CI流程发现循环引用立即终止构建。曾经有个深层循环依赖导致生产环境打包体积暴涨300%这个检查现在是我们CI的第一道防线。5. 构建与缓存优化5.1 Turborepo管道配置turbo.json典型配置{ pipeline: { build: { dependsOn: [^build], outputs: [dist/**] }, test: { dependsOn: [build], inputs: [src/**/*.ts, test/**/*.ts], outputs: [coverage/**] }, lint: { cache: false } } }性能优化技巧对node_modules重依赖的包如Babel插件标记cache: falseI/O密集型任务设置persistent: true内存不足时添加concurrency: 5限制并行数5.2 构建产物标准化每个包必须包含dist/- 编译输出types/- 类型声明package.json中明确{ main: ./dist/index.js, types: ./types/index.d.ts, files: [dist, types] }我们曾因漏声明files字段导致NPM发布包含测试代码引发安全问题。现在通过prepublishOnly脚本自动检查。6. 代码规范与工具链6.1 统一代码风格根目录.eslintrc.js关键配置module.exports { extends: [ eslint:recommended, plugin:typescript-eslint/recommended, prettier ], parserOptions: { project: ./tsconfig.json, tsconfigRootDir: __dirname, }, rules: { typescript-eslint/consistent-type-imports: error, import/no-relative-parent-imports: error } }特别推荐import/no-relative-parent-imports规则强制使用alias导入避免类似../../../utils的混乱引用。6.2 Git工作流约定我们的.gitignore必须包含# 依赖 **/node_modules **/package-lock.json # 构建产物 **/dist **/types # 开发文件 *.local .env每个提交前自动执行多包并行lint通过turbo run lint受影响包的类型检查变更文件的prettier格式化7. 环境变量管理7.1 分层环境配置采用三级环境变量体系根目录.env- 全局共享包目录.env- 包专用*.env.local- 本地开发通过dotenv-cli实现变量继承dotenv -e ../.env -- vite build重要教训永远不要将monorepo根目录的node_modules加入NODE_PATH这会导致不同包加载到错误的依赖版本我们曾因此浪费两天排查一个诡异的React版本冲突问题。8. 测试策略8.1 测试代码组织每个包的测试必须放在__tests__目录使用.test.ts后缀类型检查作为测试的一部分我们的jest.config.js包含module.exports { preset: ts-jest, testMatch: [**/__tests__/**/*.test.ts], moduleNameMapper: { ^libs/(.*)$: rootDir/packages/libs/$1/src, ^apps/(.*)$: rootDir/packages/apps/$1/src } }8.2 测试数据共享通过packages/libs/__fixtures__集中管理测试数据其他包通过软链接访问。绝对禁止直接复制测试数据我们曾因数据不同步导致测试通过但生产环境失败的惨剧。9. 文档规范9.1 包级文档要求每个包必须包含README.md- 功能说明API.md- 类型签名文档通过TypeDoc生成CHANGELOG.md- 变更记录通过脚本检查文档完整性#!/bin/bash for pkg in packages/*; do [ ! -f $pkg/README.md ] echo Missing README in $pkg exit 1 done9.2 类型文档自动化scripts/generate-typedoc.js:const TypeDoc require(typedoc); const app new TypeDoc.Application(); app.bootstrap({ entryPoints: [packages/libs/utils/src/index.ts], tsconfig: packages/libs/utils/tsconfig.json }); const project app.convert(); if (project) { app.generateDocs(project, packages/libs/utils/docs); }通过Git钩子在API变更时自动更新文档确保文档与代码同步。10. 持续集成优化10.1 CI流水线设计.github/workflows/ci.yml关键步骤jobs: build: strategy: matrix: package: [libs/utils, apps/web] steps: - uses: actions/checkoutv3 - run: npm install - run: npx turbo run build --filter./packages/${{ matrix.package }} - run: npx turbo run test --filter./packages/${{ matrix.package }}优化技巧按变更路径智能触发构建通过--filter缓存TurboRepo构建产物并行执行非依赖任务10.2 本地开发与CI一致性通过Docker保证环境一致FROM node:18-alpine WORKDIR /monorepo COPY package.json . COPY packages/libs/utils/package.json packages/libs/utils/ RUN npm install COPY . .我们要求所有开发者定期执行docker build验证本地环境这解决了在我机器上能跑的经典问题。11. 升级与迁移策略11.1 TypeScript版本升级我们的升级检查清单在根目录创建tsconfig.next.json测试新版本逐个包执行npx tsc --noEmit --project tsconfig.next.json使用typescript-eslint的typescript-eslint/no-unsafe-*规则捕捉潜在问题先升级开发依赖如jest、eslint插件最后更新项目代码11.2 架构变更管理重大变更必须在packages/_prototypes下创建原型验证编写迁移指南含回滚方案分阶段发布先alpha→beta→stable提供自动化迁移脚本去年我们将状态管理库从MobX迁移到Zustand通过这个流程实现了零宕机升级。12. 监控与维护12.1 健康度监控每日自动检查构建时间变化类型检查错误数测试覆盖率波动依赖安全警报通过PrometheusGrafana可视化监控面板当指标异常时自动创建GitHub Issue。12.2 依赖更新策略采用阶梯式更新开发依赖自动更新通过Renovate生产依赖每周人工审核后更新重大版本专项升级任务对于React等核心库我们会先在实验分支验证两周再合并到主分支。