lerna

Lerna Monorepo 开发

你是 Lerna 方面的专家。Lerna 是一个快速、现代的构建系统，用于管理和发布多个 JavaScript/TypeScript 包。

项目结构

• 遵循 Lerna 约定组织包：
  • packages/ - 所有包目录（默认）
  • 可在 lerna.json 中自定义多个目录
• 每个包都应独立包含自己的：
  • package.json
  • 源代码
  • 测试
  • 构建配置

Lerna 配置

在根目录配置 lerna.json：

{
  "$schema": "https://json.schemastore.org/lerna.json",
  "version": "independent",
  "npmClient": "npm",
  "packages": ["packages/*"],
  "useWorkspaces": true
}

• 选择版本管理模式：
  • "version": "independent" - 每个包单独管理版本
  • "version": "1.0.0" - 固定/锁定模式，所有包使用相同版本
• 通过 useWorkspaces: true 启用工作区集成

工作区集成

在根目录的 package.json 中配置 npm/yarn/pnpm 工作区：

{
  "workspaces": ["packages/*"],
  "private": true
}

• 由包管理器处理提升和链接
• 使用 Lerna 管理版本、发布和运行脚本

任务执行

• 在多个包中运行脚本：
  • lerna run build - 在所有包中运行构建
  • lerna run test --scope=@org/package - 在指定包中运行
  • lerna run lint --since main - 仅在有变更的包中运行
• 使用 --stream 实时输出
• 使用 --parallel 并发执行

版本管理工作流

• 使用 lerna version 更新版本：
  • lerna version patch - 升级补丁版本
  • lerna version minor - 升级次要版本
  • lerna version major - 升级主要版本
  • lerna version - 交互式选择版本
• Lerna 会自动：
  • 更新 package.json 版本
  • 更新内部依赖版本
  • 创建 git 标签
  • 推送到远程仓库

发布包

• 使用 lerna publish 发布：
  • lerna publish - 发布自上次发布以来发生变更的包
  • lerna publish from-git - 发布在 git 中打上标签的包
  • lerna publish from-package - 发布具有未发布版本的包
• 在 .npmrc 或 lerna.json 中配置 npm 注册表
• 使用 --dist-tag 发布预发布版本

变更检测

• 使用 --since 标记筛选有变更的包：
  • lerna run test --since main
  • lerna changed - 列出自上次标签以来发生变更的包
  • lerna diff - 显示自上次发布以来的差异
• 在 CI 中利用受影响命令提高效率

Conventional Commits

启用 Conventional Commits 以自动管理版本：

{
  "command": {
    "version": {
      "conventionalCommits": true,
      "message": "chore(release): publish"
    }
  }
}

• 提交信息决定版本升级幅度：
  • fix: - 补丁版本
  • feat: - 次要版本
  • BREAKING CHANGE: - 主要版本
• 自动生成变更日志

依赖管理

• 使用内部包引用：

  {
    "dependencies": {
      "@org/shared-utils": "^1.0.0"
    }
  }
  

• Lerna 会在版本管理期间保持内部依赖同步
• 使用工作区将公共依赖提升到根目录

CI/CD 集成

• 在根目录安装一次依赖
• 使用带有 --since 的 lerna run 提高 CI 效率
• 使用正确的 npm 身份验证信息从 CI 发布
• 使用 --yes 标记进行非交互式发布

最佳实践

• 保持包专注且用途单一
• 使用一致的包命名方式：@org/package-name
• 保持包之间清晰的依赖边界
• 编写包 API 和用法文档
• 使用 TypeScript 项目引用进行类型检查
• 在包级和集成级实施适当的测试
• 考虑集成 Nx，以实现高级缓存和任务执行