Lerna 贡献开发指南：环境搭建、测试体系、本地发布与 E2E 验证全流程

Lerna 贡献开发指南环境搭建、测试体系、本地发布与 E2E 验证全流程【免费下载链接】lernaLerna is a fast, modern build system for managing and publishing multiple JavaScript/TypeScript packages from the same repository.项目地址: https://gitcode.com/gh_mirrors/le/lerna本文以 Lerna 仓库的 CONTRIBUTING.md 为主线完整梳理了从开发环境准备、仓库代码结构到单元测试、集成测试、E2E 测试、本地 npm 发布与正式发布的全套协作流程并结合仓库内真实的package.json、tools/scripts下的脚本与e2e测试工程做源码级印证。读完本文你可以在本地完整搭建 Lerna 开发环境跑通任意层级的测试并借助 verdaccio 在本地发布一个私有版本的lernaCLI 进行手动验证最终掌握向该项目提交 Issue 与 PR 的标准姿势。一、环境准备用 Volta 锁定 Node 与 npm 版本Lerna 仓库推荐使用 Volta 中的volta字段自动切换到对应版本{ volta: { node: 26.5.0, npm: 12.0.1, yarn: 1.22.19 } }这里的node、npm版本正是核心贡献者与 GitHub Actions 工作流实际使用的版本packageManager字段也声明为npm12.0.1。Volta 的价值在于“自动同步”核心贡献者与本仓库 CI 使用同一套 Node/npm 版本避免“我本地能跑、CI 挂了”的版本漂移问题。如果你不想使用 Volta也可以手动将全局 Node/npm 对齐到volta配置中声明的版本并留意随仓库演进不断同步。任何时候都可以在仓库内运行以下命令核对当前版本node --version npm --version确认版本后克隆并安装依赖依赖已锁定直接用npm ci做干净安装git clone https://gitcode.com/gh_mirrors/le/lerna.git cd lerna npm ci二、代码结构总览六大目录各司其职仓库源码主要划分为六类目录理解它们的分工是后续定位代码、编写测试的前提e2e最新的端到端测试代码以最接近真实用户的方式直接调用lernaCLI。从目录结构看每个命令info、changed、clean、publish、version、run等都有独立的 Nx 项目project.json例如 e2e/info/project.json 定义了名为e2e-info的项目及e2e、prepare-for-e2e等 targetintegration介于单元测试与 E2E 之间的“遗留”测试代码。文档明确建议新测试优先写 E2E 而非 integration因为 E2E 价值更高libs被组合进发布包、或辅助单元/E2E 测试的源码。例如 libs/core 是核心逻辑库src/lib 下包含大量实现libs/commands 下按changed、clean、publish、version等命令拆分子项目libs/child-process 提供子进程封装libs/test-helpers 提供测试辅助设施packages真正发布到 npm 的包。目前核心是 packages/lerna内含 CLI 入口src/cli.ts、命令实现、迁移脚本migrations.json与 JSON Schemapackages/lerna/schemas/lerna-schema.jsontools维护仓库用的工具脚本与补丁等例如本地 npm registry 脚本 tools/scripts/local-registry.sh 与发布脚本 tools/scripts/lerna-release.mjswebsite官网 https://lerna.js.org 的源码最终发布到 GitHub Pages。三、提交指南Issue 与 PR 的标准流程3.1 提交 Issue 之前先搜索提交 Issue 前请先检索现有 issue 列表你的问题可能已经存在且被解决或讨论中已给出可用的 workaround。确认是新问题后维护者修复 bug 的前提是能够复现并确认因此提交时请尽量携带以下关键信息npx lerna info的输出环境诊断信息yarn.lock或package-lock.json依赖锁定文件最重要的一个能失败的最小复现用例。最小复现能帮维护者快速确认 bug或指出编码问题、确认修的是正确的问题。文档特别提到一个经验现象用户在准备最小复现仓库的过程中往往自己就发现了问题所在。如果实在难以从大型代码库中抽取关键片段也请尽量隔离出问题域。新 Issue 通过官方的 issue form 提交。3.2 提交 PR遵循 GitHub 标准 fork 模型本项目遵循 GitHub 标准的 fork 工作流先 fork 仓库再提交 Pull Request。PR 中建议同时说明改动动机、测试覆盖情况并确保本地已通过下文相关的测试与 lint。四、测试体系从单元测试到 E2E 的完整命令4.1 单元测试仓库使用 Nx Vitest 组织测试npm test实际映射到nx run-many -t test见 package.json 的 scripts。常用命令如下# 运行全部单元测试 npm test # 监听模式文件变更自动重跑 npm test -- --watch # 只测某个项目/包project 名称见各 project.json 的 name 字段 npx nx test core npx nx test lerna # 其余项目同理 # 监听某个项目/包的测试 npx nx test core --watch npx nx test lerna --watch其中core对应 libs/core/project.json 定义的 Nx 项目lerna对应 packages/lerna/project.json。以npx nx test lerna为例会执行该包的 Vitest 配置vitest.config.ts包含 packages/lerna/src 下的单元测试如esm-compat.spec.ts。4.2 集成测试# 运行全部集成测试映射为 nx integration integration --maxWorkers2 npm run integration # 只跑某个测试文件 npm run integration -- --testFile lerna-add.spec.ts # 监听变更 npm run integration -- --watch # 监听并只跑某个文件 npm run integration -- --testFile lerna-add.spec.ts --watch集成测试代码位于 integration/tests如lerna-changed.spec.ts、lerna-publish-fixed.spec.ts等配合 integration/tests/fixtures下的 fixture 使用。再次强调新测试优先写入 e2e而不是继续往这里增加。4.3 Lint 与代码格式# 全量 lint映射为 nx run-many -t lint npm run lint # 自动修复 lint 错误 npm run lint -- --fix建议在编辑器中安装 ESLint 插件如vscode-eslint以获得即时反馈。此外仓库还提供了 prettier 检查与写入脚本npm run format:check与npm run format:write。五、本地 CLI 测试基于 verdaccio 的私有 npm 源如果你希望像真实用户一样“安装并使用”一个本地构建的 Lerna 版本可以借助 verdaccio 在本地起一个 npm registry。整个流程需要两个终端窗口终端 1启动长期运行的本地 registryverdaccio 实例npm run local-registry start该命令实际执行yarn verdaccio --config ./.verdaccio/config.yml见 tools/scripts/local-registry.sh 的start分支。终端 2登录本地 registry无需真实凭据用test/test/testtest.io即可npm adduser --registry http://localhost:4873终端 2发布一个本地版本的 Lerna版本号任意、建议选一个与当前主版本不同的不存在版本例如999.9.9npm --registryhttp://localhost:4873/ run lerna-release 999.9.9 --local之后你就可以在任何地方通过--registry标志安装这个本地版本例如初始化一个新的 Lerna 工作区cd /some/path/on/your/machine npx --registryhttp://localhost:4873/ lerna999.9.9 init npm --registryhttp://localhost:4873/ install npx lerna --version # 999.9.9两个重要注意事项测试结束后务必关闭本地 registry关闭终端 1并执行npm run local-registry disable恢复 registry 指向。否则下次npm install会把 lockfile 中的解析地址改成localhost:4873。也可以执行npm run local-registry clear清空本地 registry 里的全部包。从 tools/scripts/local-registry.sh 可以看到enable/disable/clear/start四个子命令的实现enable会把 npm/yarn registry 指向http://localhost:4873/disable删除该配置并回显当前 registryclear删除./build/local-registry/storage。要使用这个新发布的本地版本你需要新建一个工作区或把目标包版本改为新版本号如lerna: ^999.9.9后重新npm install。5.1 深入lerna-release 脚本的本地/正式发布差异tools/scripts/lerna-release.mjs 是本地与正式发布共用的核心脚本它直接调用lerna/commands/publish与lerna/commands/version并透传大量参数。理解其关键选项有助于你正确使用上面的命令选项默认值说明--local/-ltrue是否只发布到本地。为true时不做 conventional commits 版本推断、不打 git tag、不创建 GitHub Release版本默认取你传入的版本号缺省为minor日志级别默认error为false时走正式发布流程--taglocal 时latest否则nextnpm dist-tag可选next、latest、previous--preidbeta预发布版本标识可选alpha、beta、rc形如1.0.0-beta.0--gitRemoteorigin发布 git tag 的目标 remote 名--loglevelinfolocal 为error日志级别可选error、info、debug--noInteractivefalse关闭交互式操作适合 CI--skipPublishfalse只执行 version 不执行 publish用于验证版本逻辑会打印警告--clearLocalRegistrytrue发布前清空本地 registry允许重复发布同版本脚本还内置了安全校验--local模式下要求当前 registry 必须指向 localhost否则报错正式发布--local false则要求设置GH_TOKEN环境变量且除非传--forceregistry 不能被设置为 localhost防止误发到真实 npm。--local模式还会在结束后恢复lerna.json、根package.json、package-lock.json与packages/lerna/package.json的原始内容。六、E2E 测试最接近真实用户的高价值测试E2E 测试会真正把包构建、版本化并发布到本地 npm registry同样借助 verdaccio然后直接调用lernaCLI 验证行为因此是价值最高的测试但也比单元测试慢得多。它们被拆分为多个独立 e2e 项目可单独运行并受益于 Nx 的细粒度缓存。前提运行全部 e2e 套件需要安装pnpm版本8.10.2 或更高因为部分 E2E fixture 需要 pnpm 工作区。6.1 常规 E2E 项目除e2e-run-task-runner外以测试lerna info命令的e2e-info项目为例npx nx e2e e2e-info可以向底层 vitest 进程转发参数例如用-t按名称过滤测试、用-u更新快照# 只匹配 describe()/it() 描述中包含 qqqq 的测试并更新快照 npx nx e2e e2e-info -t qqqq -u注意无论传入什么 vitest 参数包的构建、版本化与发布流程都是一样的见 e2e/info/project.json 中prepare-for-e2etarget 与各 e2e/*/src/test-setup.ts 的分工。6.2 任务执行器测试e2e-run-task-runner的特别之处任务执行器task-runner本身会在 Node 中派生出多层嵌套子进程再把它们包进测试用的 Node 子进程来收集 stdout/stderr 会变得困难——因为 Node 对 stdout/stderr 流的写入顺序不作保证导致测试中断言的行序可能不确定。因此 task-runner 测试改用bash 调用 lerna CLI 并先把输出写到磁盘Node 测试再读取这些文件做断言从而消除大部分非确定性。首先确保本地 registry 已运行且包已发布npx nx prepare-for-e2e e2e-run-task-runner然后执行 bash 脚本运行测试e2e/run/task-runner/src/run-tests.sh该脚本接收 task-runner 源码目录下的子目录名作为参数便于只跑某个子集例如e2e/run/task-runner/src/run-tests.sh env-files传入--update-snapshots或-u时会以 vitest 的-u选项更新既有快照e2e/run/task-runner/src/run-tests.sh --update-snapshots # 更新全部测试快照 e2e/run/task-runner/src/run-tests.sh env-files --update-snapshots # 只更新 env-files 的快照从 e2e/run/task-runner/src/run-tests.sh 的实现可以看到它遍历src/下每个子目录并调用其exec.sh而 e2e/run/task-runner/src/utils.sh 中的initializeFixture通过 tools/scripts/set-e2e-root.ts 在/tmp/lerna-e2eCI 下为临时目录生成 fixture进入lerna-workspace后把各命令输出写入node_modules/.lerna-test-outputs最后runAssertions调用 vitest 执行对应的assertions.spec.ts。以 e2e/run/task-runner/src/task-runner/exec.sh 为例它会真实执行npx lerna run print-name及其--stream、--parallel、--no-prefix、--profile、--npm-clientyarn、--ci等变体覆盖任务执行器的主要参数面。当前源码中共有env-files、multiple-targets、pnpm、task-runner、with-nx-config、incompatible-options等十余个测试套件见 e2e/run/task-runner/src。七、发布正式 Release 流程如果你拥有 Lerna GitHub 组织的成员权限、在 npm 的lernaorg 下具备读写权限且已开启 2FA即可发起一次正式发布。首先在仓库根目录创建本地.env文件根目录的 .env.example 提供了模板以注入所需环境变量。根.env文件永远不会进入版本控制。然后运行发布脚本npx env-cmd npm run lerna-release -- --local false这里的npm run lerna-release映射到nx build lerna --no-dte --no-cloud node tools/scripts/lerna-release.mjs见 package.json先构建lerna包再执行发布脚本。--local false表示走正式发布路径——脚本会进行 npm 登录、按 conventional commits 推断版本默认发布为nexttag、创建 GitHub Release并依据.env中的凭据完成 npm 发布。正式发布前请确认当前 registry 已恢复为官方 npm即已执行npm run local-registry disable因为脚本会强制校验这一点。八、常见问题速查版本对不上检查node --version与npm --version是否匹配根 package.json 的volta配置或直接安装 Volta 自动接管。lockfile 被改成 localhost:4873说明本地 registry 没有关闭执行npm run local-registry disable后重新npm install。E2E 输出顺序不稳定这正是 task-runner 测试改用 bash 写盘再断言的原因不要绕过 run-tests.sh 直接手写 Node 包装。新测试该放哪优先放 e2e价值最高integration 仅作为既有遗留代码存在不宜新增。通过以上流程你既可以作为贡献者规范地提交 Issue 与 PR也可以作为使用者在本地产出一个可信的 Lerna 构建进行实验整个过程均有仓库内真实脚本与测试工程作为支撑。【免费下载链接】lernaLerna is a fast, modern build system for managing and publishing multiple JavaScript/TypeScript packages from the same repository.项目地址: https://gitcode.com/gh_mirrors/le/lerna创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考