前端Lerna管理规范书

前端Lerna管理规范书一、Lerna基础认知1.1Lerna定义与核心价值Lerna是一款基于JavaScript的多包管理工具，专为管理拥有多个子项目的仓库而设计。它通过提供一套标准化的工作流，帮助开发者在单一代码仓库（Monorepo）中高效管理多个相互关联或独立的前端包。其核心价值体现在以下几个方面：统一版本管理：支持两种版本管理模式，Fixed/Locked模式下所有包共享同一版本号，适合高度耦合的项目；Independent模式下各包可独立更新版本，适用于相对独立的包集合。依赖优化：自动检测包之间的内部依赖，在安装时进行链路优化，避免重复安装相同依赖，同时支持将公共依赖提升到根目录，减少存储空间占用。批量执行命令：能够在所有包或指定包中批量执行npm脚本命令，如安装依赖、构建、测试等，大幅提升多包项目的开发效率。发布流程简化：提供自动化的发布流程，包括版本号更新、CHANGELOG生成、Git标签创建以及npm包发布等，降低多包发布的复杂度。1.2Lerna适用场景Lerna并非适用于所有前端项目，以下场景更能体现其优势：组件库开发：当项目包含多个可复用的UI组件、工具函数包时，使用Lerna可以统一管理这些组件的版本和依赖，方便组件的独立发布和维护。大型应用拆分：对于大型前端应用，可按照功能模块拆分为多个子包，每个子包独立开发、测试和部署，同时通过Lerna保证整体的一致性。开源项目集合：开源组织或个人维护多个相关的开源包时，Lerna能够简化版本发布和依赖管理流程，提升项目的可维护性。二、Lerna项目初始化2.1环境准备在开始使用Lerna之前，需要确保开发环境满足以下要求：Node.js：推荐安装LTS版本（如18.x或20.x），Lerna对Node.js版本有一定要求，过低版本可能导致功能异常。npm或yarn：确保已安装npm（通常随Node.js一起安装）或yarn包管理器，用于执行依赖安装和脚本命令。Git：Lerna依赖Git进行版本控制和发布流程，需提前初始化Git仓库并配置好远程仓库地址。2.2全局安装与项目初始化2.2.1全局安装Lerna打开终端，执行以下命令全局安装Lerna：npminstall-glerna安装完成后，可通过lerna--version命令验证安装是否成功。2.2.2初始化Lerna项目创建项目根目录并进入，执行初始化命令：mkdirmy-lerna-project&&cdmy-lerna-projectlernainit执行完成后，项目根目录会生成以下结构：my-lerna-project/├──lerna.json#Lerna配置文件├──package.json#根目录package.json└──packages/#存放所有子包的目录2.3配置文件详解2.3.1lerna.jsonlerna.json是Lerna的核心配置文件，主要配置项如下：{"$schema":"node_modules/lerna/schemas/lerna-schema.json","version":"0.0.0",#版本号，Fixed模式下为统一版本，Independent模式下为"independent""npmClient":"npm",#使用的包管理器，可选npm或yarn"command":{"publish":{"ignoreChanges":["ignored-file","*.md"],#发布时忽略的文件或目录"message":"chore(release):publish%s"#发布时的Git提交信息模板},"bootstrap":{"ignore":"component-*",#执行bootstrap命令时忽略的包"npmClientArgs":["--no-package-lock"]#传递给npm/yarn的额外参数}},"packages":["packages/*"#子包的匹配路径，支持通配符]}2.3.2根目录package.json根目录的package.json主要用于管理项目的开发依赖和全局脚本命令，示例如下：{"name":"my-lerna-project","private":true,#标记为私有包，避免被意外发布到npm"devDependencies":{"lerna":"^7.0.0"},"scripts":{"bootstrap":"lernabootstrap",#执行所有包的依赖安装"build":"lernarunbuild",#执行所有包的build脚本"test":"lernaruntest"#执行所有包的test脚本}}三、子包管理规范3.1子包创建与命名3.1.1创建子包在packages目录下创建子包，可手动创建目录结构或使用Lerna命令快速创建：lernacreatepackage-name执行该命令后，Lerna会自动在packages目录下生成子包的基本结构，包括package.json、README.md、源码目录等。3.1.2子包命名规范子包命名应遵循以下原则：清晰明确：名称应准确反映子包的功能，避免使用模糊或歧义的词汇。例如，一个按钮组件包可命名为@my-org/button，而不是@my-org/ui-1。统一前缀：对于组织或公司内部的包，建议使用统一的scope前缀（如@my-org/），便于识别和管理。小写短横线分隔：名称全部使用小写字母，单词之间用短横线分隔，符合npm包的命名惯例。3.2子包package.json配置子包的package.json是包的核心配置文件，以下是关键配置项的规范：3.2.1基本信息{"name":"@my-org/button","version":"1.0.0","description":"Areusablebuttoncomponent","main":"lib/index.js",#包的入口文件，通常指向编译后的代码"module":"es/index.js",#ES模块入口，支持tree-shaking"types":"lib/index.d.ts",#TypeScript类型定义文件路径"files":[#发布到npm时包含的文件或目录"lib","es","README.md"]}3.2.2依赖管理内部依赖：当子包依赖于项目中的其他子包时，应使用相对版本号或^前缀，例如：{"dependencies":{"@my-org/utils":"^1.0.0"}}Lerna在执行bootstrap命令时会自动将内部依赖链接到本地包，方便开发调试。外部依赖：对于第三方依赖，应明确指定版本范围，优先使用固定版本号或^前缀，避免因依赖版本更新导致的兼容性问题。同时，将开发依赖（如构建工具、测试框架等）与生产依赖分开配置：{"dependencies":{"react":"^18.0.0"},"devDependencies":{"webpack":"^5.0.0","jest":"^29.0.0"}}3.3子包目录结构规范子包的目录结构应保持统一，便于团队成员理解和维护，推荐结构如下：packages/button/├──src/#源码目录│├──index.tsx#组件入口文件│├──Button.tsx#组件实现文件│└──styles/#样式文件目录├──lib/#编译后的CommonJS模块目录├──es/#编译后的ES模块目录├──__tests__/#测试用例目录│└──Button.test.tsx├──package.json└──README.mdsrc/：存放未编译的源码文件，按照功能或模块进行组织。lib/和es/：分别存放编译后的CommonJS和ES模块代码，通常由构建脚本生成。tests/：存放单元测试、集成测试等用例文件，测试文件应与源码文件一一对应。README.md：包含子包的功能介绍、使用方法、API文档等信息，方便其他开发者快速了解和使用该包。四、依赖管理规范4.1依赖安装与链路4.1.1安装所有依赖在项目根目录执行以下命令，Lerna会自动安装所有子包的依赖，并处理内部依赖的链路：lernabootstrap该命令会遍历所有子包，执行npminstall或yarninstall，同时将内部依赖链接到本地对应的包，实现本地开发时的依赖引用。4.1.2安装单个依赖如需为所有子包或指定子包安装某个依赖，可使用以下命令：为所有子包安装开发依赖：lernaaddjest--dev为指定子包安装生产依赖：lernaadd@my-org/utils--scope=@my-org/button4.2依赖提升策略Lerna默认会将子包之间的公共依赖提升到根目录的node_modules中，以减少重复安装。但在某些情况下，可能需要调整依赖提升策略：强制提升：对于所有子包都依赖的第三方包，可在根目录的package.json中手动指定该依赖，Lerna会自动将子包中的对应依赖删除并统一使用根目录的版本。禁止提升：如果某个依赖在不同子包中需要不同版本，可在子包的package.json中明确指定版本，并在lerna.json中配置hoist:false禁止依赖提升，但这可能会导致重复安装和存储空间占用增加。4.3依赖更新与清理4.3.1更新依赖当需要更新子包的依赖版本时，可使用以下方式：手动修改子包package.json中的依赖版本号，然后执行lernabootstrap重新安装。使用npmupdate或yarnupgrade命令在子包目录中单独更新依赖。4.3.2清理依赖如需清理所有子包的node_modules目录和锁文件，可执行：lernaclean该命令会删除所有子包的node_modules目录，但不会删除根目录的node_modules。五、开发与构建规范5.1脚本命令统一为了保证所有子包的开发和构建流程一致，应统一脚本命令的名称和功能。以下是常见脚本命令的规范：{"scripts":{"build":"webpack--modeproduction",#生产环境构建"build:dev":"webpack--modedevelopment",#开发环境构建"dev":"webpack-dev-server--modedevelopment",#开发服务器启动"test":"jest",#执行单元测试"test:watch":"jest--watch",#监听文件变化并自动执行测试"lint":"eslintsrc",#代码风格检查"lint:fix":"eslintsrc--fix"#自动修复代码风格问题}}所有子包应尽量遵循上述脚本命令命名，方便使用lernarun命令批量执行。5.2构建流程规范5.2.1构建输出子包的构建输出应遵循以下规范：同时输出CommonJS和ES模块两种格式，分别存放在lib和es目录中，以支持不同的模块系统。构建产物应包含类型定义文件（如.d.ts），方便TypeScript项目使用。构建过程中应清除之前的构建产物，避免旧文件残留。5.2.2构建工具选择推荐使用webpack、Rollup或Vite等现代化构建工具，根据子包的类型和需求选择合适的工具：组件库：优先选择Rollup，其更适合构建库文件，支持tree-shaking和多种模块格式输出。应用模块：可使用webpack或Vite，两者都提供了丰富的插件生态和开发服务器支持，适合复杂应用的构建。5.3代码质量保证5.3.1代码风格检查所有子包应统一使用ESLint进行代码风格检查，根目录可配置共享的ESLint规则，子包通过继承根目录的配置来保证代码风格一致。根目录.eslintrc.js示例：module.exports={root:true,extends:['eslint:recommended','plugin:react/recommended','@typescript-eslint/recommended'],parser:'@typescript-eslint/parser',plugins:['react','@typescript-eslint'],settings:{react:{version:'detect'}}};子包的.eslintrc.js可简化为：module.exports={extends:'../../.eslintrc.js'};5.3.2单元测试每个子包都应编写单元测试用例，使用Jest、Vitest等测试框架。测试用例应覆盖主要功能点，包括组件的渲染、交互逻辑、工具函数的输入输出等。测试文件应与源码文件放在同一目录或单独的__tests__目录中，命名格式为[filename].test.tsx或[filename].spec.tsx。六、版本管理与发布规范6.1版本号策略6.1.1版本号格式遵循语义化版本（SemanticVersioning）规范，版本号格式为主版本号.次版本号.修订号：主版本号（Major）：当进行不兼容的API更改时，递增主版本号。次版本号（Minor）：当添加向后兼容的新功能时，递增次版本号。修订号（Patch）：当进行向后兼容的问题修正时，递增修订号。6.1.2版本管理模式选择根据项目需求选择合适的版本管理模式：Fixed/Locked模式：所有子包共享同一版本号，适合高度耦合的项目，版本更新时所有包的版本号同步递增。在lerna.json中配置：{"version":"1.0.0"}Independent模式：各子包独立更新版本号，适用于相对独立的包集合。在lerna.json中配置：{"version":"independent"}6.2发布流程规范6.2.1发布前准备在执行发布命令之前，需完成以下准备工作：确保所有子包的代码已提交到Git仓库，且工作区干净无未提交的修改。运行所有子包的测试用例，确保代码质量符合要求。检查CHANGELOG文件，确保版本更新的内容已正确记录。6.2.2执行发布命令根据版本管理模式选择对应的发布命令：Fixed模式发布：lernapublish执行该命令后，Lerna会提示选择要更新的版本号（patch、minor、major或自定义版本），然后自动完成版本号更新、CHANGELOG生成、Git标签创建以及npm包发布等流程。Independent模式发布：lernapublish--independentLerna会逐个询问每个子包的版本更新类型，完成后分别更新各包的版本号并发布。6.2.3发布后处理发布完成后，需进行以下操作：将发布后的代码和标签推送到远程Git仓库：gitpush&&gitpush--tags通知团队成员版本更新信息，包括更新内容、版本号等。6.3CHANGELOG管理CHANGELOG是记录版本变更内容的重要文件，Lerna支持自动生成CHANGELOG。以下是CHANGELOG的规范：每个版本的变更内容应按照类型分类，如Features（新功能）、BugFixes（问题修复）、BreakingChanges（不兼容变更）等。变更内容应简洁明了，描述变更的具体内容和影响，必要时可关联相关的Issue或PullRequest链接。CHANGELOG文件应存放在子包的根目录或项目根目录，推荐使用CHANGELOG.md作为文件名。七、协作与团队规范7.1Git工作流规范在多包项目中，统一的Git工作流是保证代码质量和协作效率的关键，推荐使用GitFlow或GitHubFlow工作流：7.1.1GitFlow主分支（master）：存放稳定的发布版本，每次发布后将代码合并到master分支并打标签。开发分支（develop）：日常开发的主分支，所有功能开发完成后合并到develop分支进行集成测试。功能分支（feature/*）：用于开发新功能，从develop分支检出，开发完成后合并回develop分支。发布分支（release/*）：用于版本发布前的准备工作，从develop分支检出，完成测试和修复后合并到master和develop分支。热修复分支（hotfix/*）：用于修复生产环境的紧急问题，从master分支检出，修复完成后合并到master和develop分支。7.1.2GitHubFlowGitHubFlow是一种更简洁的工作流，适用于持续发布的项目：主分支（main）：始终保持可发布的状态。功能分支：所有开发工作都在从main分支检出的功能分支上进行。PullRequest：功能开发完成后，提交PullRequest进行代码审查。合并与部署：代码审查通过后，将功能分支合并到main分支并立即部署。7.2代码审查规范代码审查是保证代码质量的重要环节，以下是代码审查的规范：审查范围：所有提交到主分支的代码都必须经过代码审查，包括新功能开发、问题修复、代码重构等。审查内容：审查代码的正确性、可读性、性能、安全性以及是否符合项目的编码规范和架构设计。审查流程：提交PullRequest后，至少需要一位团队成员进行审查，审查通过后才能合并代码。对于重大变更，需要多位核心成员参与审查。7.3文档维护规范良好的文档是项目可维护性的重要保障，以下是文档维护的规范：README文档：每个子包和项目根目录都应包含README.md文件，内容包括项目/包的介绍、安装方法、使用示例、API文档、贡献指南等。API文档：对于组件库或工具函数包，应提供详细的API文档，包括函数参数、返回值、使用示例等，可使用TypeDoc、JS