前端Monorepo管理规范书

前端Monorepo管理规范书一、Monorepo核心概念与适用场景（一）Monorepo定义与核心特征Monorepo（单一代码仓库）是一种将多个项目的代码存储在同一个版本控制系统仓库中的软件开发策略。与传统的MultiRepo（多代码仓库）模式不同，Monorepo允许团队在一个统一的环境中管理多个相关或不相关的项目，共享代码、工具链和依赖管理机制。其核心特征包括：单一入口：所有项目代码集中存储在一个仓库，开发者可通过克隆一次仓库获取所有项目的完整代码。跨项目协作：不同项目间的代码复用和依赖关系可直接在仓库内处理，无需通过包管理器发布和安装。统一管理：版本控制、构建流程、测试策略和部署机制可在仓库层面统一配置，减少重复工作。（二）Monorepo适用场景Monorepo并非适用于所有团队和项目，以下场景更能体现其价值：多项目共享代码：当团队维护多个存在大量公共代码的项目时，如组件库、工具函数、业务逻辑模块等，Monorepo可实现代码的无缝复用，避免重复开发和版本不一致问题。大规模团队协作：大型团队中，不同子团队负责不同项目但存在业务关联，Monorepo便于跨团队协作，统一技术栈和开发规范，提升整体开发效率。依赖关系复杂：项目间存在复杂的依赖链，如A项目依赖B项目的某个模块，B项目又依赖C项目的功能，Monorepo可清晰管理这些依赖，确保依赖版本的一致性。统一技术栈：团队采用统一的技术栈和工具链，如统一的构建工具、测试框架、代码规范等，Monorepo便于集中配置和维护这些工具，降低学习成本和维护难度。二、Monorepo工具选型（一）主流工具对比目前前端领域常用的Monorepo工具主要有Lerna、YarnWorkspaces、Nx、TurboRepo等，各工具的特点和适用场景如下：工具名称核心优势适用场景局限性Lerna成熟稳定，支持版本管理和包发布，社区活跃中小型团队，需要管理多个npm包的项目构建速度较慢，缺乏内置的缓存机制YarnWorkspaces与Yarn包管理器深度集成，依赖安装高效以Yarn为包管理器的项目，注重依赖管理效率功能相对基础，缺乏高级构建和调度能力Nx强大的构建缓存、任务调度和代码生成能力大型复杂项目，需要高级构建和优化策略学习曲线较陡，配置相对复杂TurboRepo极速构建缓存，支持分布式任务执行追求构建速度的大型项目，多语言项目兼容生态相对较新，部分功能尚在完善中（二）工具选型建议团队规模与项目复杂度：中小型团队且项目复杂度较低时，可选择Lerna或YarnWorkspaces，配置简单，学习成本低；大型团队或复杂项目优先考虑Nx或TurboRepo，其强大的构建优化和任务调度能力可显著提升开发效率。包管理器兼容性：若团队已使用Yarn作为包管理器，YarnWorkspaces是天然的选择，可无缝集成；若使用npm或pnpm，Lerna、Nx和TurboRepo均提供良好支持。构建速度需求：对构建速度要求极高的项目，如大型前端应用、组件库等，TurboRepo或Nx的构建缓存和并行执行功能可大幅缩短构建时间。生态与社区支持：Lerna和YarnWorkspaces发展时间较长，社区资源丰富，问题解决方案较多；Nx和TurboRepo作为新兴工具，生态正在快速完善，适合对新技术接受度较高的团队。三、Monorepo仓库结构设计（一）基础结构原则清晰分层：仓库结构应遵循分层设计原则，将不同类型的代码和资源进行合理划分，便于管理和维护。模块化：每个项目或模块应保持独立，具有清晰的边界，避免代码耦合。可扩展性：结构设计应考虑未来的项目扩展，预留足够的空间，避免因新增项目导致结构混乱。一致性：统一的命名规范和目录结构，便于开发者快速定位和理解代码。（二）典型仓库结构示例以下是一个典型的前端Monorepo仓库结构：monorepo-root/├──.github/#GitHub配置文件，如CI/CD工作流├──.husky/#Git钩子配置├──packages/#所有项目和模块的根目录│├──app-web/#Web应用项目││├──src/#源代码目录││├──package.json#项目依赖和脚本配置││├──tsconfig.json#TypeScript配置││└──webpack.config.js#Webpack构建配置│├──app-mobile/#移动端应用项目││├──src/││├──package.json││└──metro.config.js#Metro构建配置│├──ui-components/#UI组件库││├──src/││├──package.json││└──rollup.config.js#Rollup构建配置│└──utils/#工具函数库│├──src/│└──package.json├──scripts/#自定义脚本，如构建、部署、测试脚本├──.eslintrc.js#统一ESLint配置├──.prettierrc#统一Prettier配置├──lerna.json#Lerna配置（若使用Lerna）├──package.json#根目录依赖和脚本└──README.md#仓库说明文档（三）目录结构说明packages目录：核心目录，所有项目和模块均放置于此。每个子目录代表一个独立的项目或模块，具有自己的package.json和源代码目录。根目录配置文件：统一的代码规范配置（如ESLint、Prettier）、包管理器配置（如yarn.lock、package-lock.json）、Monorepo工具配置（如lerna.json、nx.json）等，确保所有项目遵循相同的规范。scripts目录：存放自定义的脚本文件，如统一的构建脚本、部署脚本、测试脚本等，便于在仓库层面执行跨项目的操作。.github目录：存放GitHub相关的配置文件，如CI/CD工作流配置（.github/workflows/），实现自动化构建、测试和部署。四、依赖管理规范（一）依赖类型划分在Monorepo中，依赖可分为以下几类，需采用不同的管理策略：根目录依赖：所有项目共享的工具和依赖，如构建工具（Webpack、Rollup）、测试框架（Jest、Cypress）、代码规范工具（ESLint、Prettier）等，安装在根目录的package.json中，避免重复安装。项目本地依赖：仅某个项目需要的依赖，如特定的业务库、第三方插件等，安装在对应项目的package.json中。内部依赖：项目间的依赖关系，如app-web项目依赖ui-components模块，需在app-web的package.json中通过相对路径或包名引用ui-components，并确保版本一致性。（二）依赖安装与更新根目录依赖安装：使用包管理器在根目录执行安装命令，如yarnadd-Dwebpack或npminstall-Dwebpack，所有项目可共享该依赖。项目本地依赖安装：进入对应项目目录，执行安装命令，如cdpackages/app-web&&yarnaddlodash，该依赖仅对app-web项目生效。内部依赖管理：当项目间存在内部依赖时，可通过Monorepo工具进行管理。如使用Lerna时，可通过lernaaddui-components--scopeapp-web将ui-components模块添加为app-web的依赖；使用YarnWorkspaces时，直接在app-web的package.json中添加"ui-components":"workspace:^1.0.0"即可。依赖更新：根目录依赖更新需在根目录执行更新命令，如yarnupgradewebpack；项目本地依赖更新进入对应项目目录执行更新命令；内部依赖更新时，需确保依赖项目的版本号正确更新，并在依赖项目中重新安装依赖以确保版本一致性。（三）依赖版本一致性保障锁定版本：使用包管理器的锁文件（如yarn.lock、package-lock.json）锁定依赖版本，确保所有开发者和环境安装的依赖版本一致。统一版本号：对于共享的第三方依赖，如React、Vue等，在根目录统一指定版本，所有项目使用相同版本，避免版本冲突。依赖检测工具：使用如dependency-cruiser、npm-check-updates等工具定期检测依赖版本，及时更新过时依赖，同时确保依赖版本的兼容性。五、构建与测试规范（一）构建流程设计统一构建工具：选择统一的构建工具，如Webpack、Rollup、Vite等，并在根目录配置基础的构建规则，各项目可根据自身需求进行扩展。增量构建与缓存：利用Monorepo工具的构建缓存功能，如Nx的计算缓存、TurboRepo的远程缓存，仅构建修改过的项目和依赖项目，大幅缩短构建时间。构建脚本统一：在根目录的package.json中定义统一的构建脚本，如"build":"lernarunbuild"（Lerna）或"build":"turborunbuild"（TurboRepo），便于一键构建所有项目或指定项目。产物输出规范：统一构建产物的输出目录，如每个项目的构建产物输出到dist目录，便于后续的部署和分发。（二）测试策略制定统一测试框架：选择统一的测试框架，如Jest、Vitest等，确保所有项目使用相同的测试语法和断言库，降低学习成本。分层测试：实施分层测试策略，包括单元测试、集成测试和端到端测试：单元测试：针对单个函数、组件或模块进行测试，确保其功能正确性，每个项目的单元测试代码放置在__tests__目录或与源代码同目录。集成测试：测试多个模块或组件之间的交互，确保整体功能正常，可在项目层面或跨项目层面进行。端到端测试：模拟用户操作流程，测试整个应用的功能和性能，使用Cypress、Playwright等工具，可在根目录统一配置和执行。测试脚本统一：在根目录的package.json中定义统一的测试脚本，如"test":"lernaruntest"或"test":"nxrun-many--target=test"，支持一键运行所有项目的测试或指定项目的测试。测试覆盖率：统一测试覆盖率要求，如要求单元测试覆盖率达到80%以上，使用jest--coverage等工具生成测试覆盖率报告，并在CI/CD流程中进行校验。六、版本管理与发布规范（一）版本号规则采用语义化版本（SemanticVersioning）规范，版本号格式为主版本号.次版本号.修订号：主版本号：当进行不兼容的API更改时，主版本号递增，如从1.0.0升级到2.0.0。次版本号：当添加向后兼容的新功能时，次版本号递增，如从1.0.0升级到1.1.0。修订号：当进行向后兼容的问题修正时，修订号递增，如从1.0.0升级到1.0.1。（二）版本管理流程版本号维护：每个项目的版本号维护在其package.json中，Monorepo工具可辅助管理版本号。如使用Lerna时，可通过lernaversion命令批量更新项目版本号，并生成CHANGELOG。分支策略：采用GitFlow或GitHubFlow等分支策略，确保版本发布的稳定性：GitFlow：使用主分支（master）、开发分支（develop）、功能分支（feature）、发布分支（release）和热修复分支（hotfix），适合大型复杂项目。GitHubFlow：以主分支为核心，所有功能开发和修复通过PullRequest合并到主分支，合并后直接发布，适合敏捷开发的小型项目。CHANGELOG生成：每次版本更新时，自动生成CHANGELOG，记录版本变更内容，包括新增功能、修复的问题、不兼容的更改等。可使用conventional-changelog、lerna-changelog等工具自动生成CHANGELOG。（三）发布流程规范发布前检查：发布前需确保所有测试通过，代码符合规范，依赖版本正确，CHANGELOG已更新。发布方式选择：根据项目类型选择合适的发布方式：npm包发布：对于组件库、工具函数库等npm包，使用Monorepo工具的发布命令，如lernapublish或npmpublish--workspaces，将包发布到npm仓库。应用部署：对于Web应用、移动端应用等，将构建产物部署到对应的服务器或云平台，如使用Docker镜像部署、云平台的自动化部署服务等。发布后验证：发布完成后，需进行验证，确保包可正常安装和使用，应用可正常访问和运行。同时，通知相关团队和用户版本更新信息。七、CI/CD流程配置（一）CI/CD核心目标CI/CD（持续集成/持续部署）的核心目标是实现代码的自动化构建、测试和部署，提升开发效率，确保代码质量，缩短交付周期。在Monorepo中，CI/CD流程需支持跨项目的自动化操作，同时兼顾构建速度和资源利用率。（二）CI/CD流程设计代码提交触发：当开发者向仓库提交代码时，自动触发CI流程，包括代码规范检查、单元测试、集成测试等。增量构建与测试：利用Monorepo工具的缓存功能，仅对修改过的项目和依赖项目进行构建和测试，减少不必要的计算，提升CI流程速度。多环境部署：支持多环境部署，如开发环境、测试环境、预发布环境和生产环境，每个环境对应不同的部署策略和配置。自动化发布：当代码合并到主分支或满足特定条件时，自动触发发布流程，将包发布到npm仓库或部署应用到生产环境。（三）主流CI/CD工具配置示例以GitHubActions为例，配置Monorepo的CI/CD流程：#.github/workflows/ci-cd.ymlname:CI/CDPipelineon:push:branches:[main,develop]pull_request:branches:[main,develop]jobs:lint:runs-on:ubuntu-lateststeps:-uses:actions/checkout@v4-name:SetupNode.jsuses:actions/setup-node@v4with:node-version:'20'cache:'yarn'-name:Installdependenciesrun:yarninstall--frozen-lockfile-name:Lintcoderun:yarnlinttest:runs-on:ubuntu-latestneeds:lintsteps:-uses:actions/checkout@v4-name:SetupNode.jsuses:actions/setup-node@v4with:node-version:'20'cache:'yarn'-name:Installdependenciesrun:yarninstall--frozen-lockfile-name:Runtestsrun:yarntest--coveragebuild:runs-on:ubuntu-latestneeds:teststeps:-uses:actions/checkout@v4-name:SetupNode.jsuses:actions/setup-node@v4with:node-version:'20'cache:'yarn'-name:Installdependenciesrun:yarninstall--frozen-lockfile-name:Buildprojectsrun:yarnbuildpublish:runs-on:ubuntu-latestneeds:buildif:github.ref=='refs/heads/main'steps:-uses:actions/checkout@v4-name:SetupNode.jsuses:actions/setup-node@v4with:node-version:'20'cache:'yarn'registry-url:'/'-name:Installdependenciesrun:yarninstall--frozen-lockfile-name:Publishpackagesrun:lernapublish--conventional-commits--yesenv:NODE_AUTH_TOKEN:${{secrets.NPM_TOKEN}}八、团队协作规范（一）代码提交规范提交信息格式：采用约定式提交（ConventionalCommits）规范，提交信息格式为：<类型>(<范围>):<描述><正文><页脚>其中，类型包括feat（新功能）、fix（修复bug）、docs（文档更新）、style（代码格式调整）、refactor（代码重构）、test（测试相关）、chore（构建或工具链更新）等；范围为提交影响的项目或模块；描述为简短的提交说明；正文为详细的提交描述（可选）；页脚可包含关联的Issue编号、不兼容更改说明等（可选）。2.提交粒度：保持提交粒度适中，每个提交对应一个独立的功能或修复，避免一次性提交大量无关代码，便于代码审查和问题定位。（二）代码审查规范审查流程：所有代码提交需通过PullRequest（PR）进行审查，至少经过一位团队成员审查通过后方可合并到主分支。审查重点：代码审查重点包括代码正确性、代码规范遵循情况、性能优化、安全性、可维护性等。审查人员需提出明确的修改意见，确保代码质量。审查时限：设定合理的审查时限，如PR提交后24小时内完成审查，避免影响开发进度。（三）分支管理规范分支命名：统一分支命名规范，如功能分支命名为feature/xxx，修复分支命名为fix/xxx，发布分支命名为release/v1.0.0，热修复分支命名为hotfix/xxx。分支清理：定期清理已合并的分支，避免仓库中存在大量无用分支，保持仓库整洁。九、Monorepo常见问题与解决方案（一）仓库体积过大问题表现：随着项目增多和代码积累，仓库体积逐渐增大，导致克隆和拉取代码速度变慢，占用大量磁盘空间。解决方案：GitLFS：对于大文件（如图片、视频、二进制文件等），使用GitLFS（LargeFileStorage）进行管理，将大文件存储在专门的服务器，仓库中仅存储文件指针，减少仓库体积。子模块：对于不常用或相对独立的项目，可考虑使用Git子模块（Submodule）进行管理，将其代码存储在独立仓库，主仓库仅引用子模块的特定版本。定期清理：定期清理仓库中的历史大文件，使用gitfilter-repo等工具重写Git历史，删除无用的大文件和提交记录。（二）构建速度缓慢问题表现：随着项目增多，全量构建时间过长，影响开发效率和CI/CD流程速度。解决方案：构建缓存：使用Monorepo工具的构建缓存功能，如Nx的计算缓存、TurboRepo的远程缓存，缓存构建结果，仅重新构建修改过的项目和依赖项目。并行构建：配置构建工具支持并行构建，同时构建多个项目，充分利用CPU资源，缩短构建时间。增量构建：优化构建工具配置，实现增量构建，仅重新编译修改过的文件，而不是全量编译。（三）依赖冲突问题表现：不同项目依赖相同第三方库的不同版本，导致依赖冲突，出现运行时错误或构建失败。解决方案：统一版本号：在根目录统一指定第三方库的版本，所有项目使用相同版本，避免版本冲突。依赖分析：使用npmls、yarnwhy等工具分析依赖树，找出冲突的依赖版本，通过调整依赖版本或使用resolutions字段强制指定依赖版本。隔离依赖：对于无法统一版本的依赖，可考虑使用项目本地依赖或通过Monorepo工具进行依赖隔离，确保各项目依赖的独立性。（四）权限管理复杂问题表现：Monorepo中包含多个项目，不同团队或开发者对不同项目的权限需求不同，权限管理变得复杂。解决方案：代码仓库权限细分：利用代码托管平台的权限管理功能，如GitHub的团队权限、GitLab的组权限，为不同团队或开发者分配不同项目的访问权限。分支保护规则：配置分支保护规则，如主分支仅允许通过PR合并，且需要特定人员审查通过，确保代码安全。访问控制列表（ACL）：对于敏感项目，可使用