Release-Please 项目中预发布版本标记问题的分析与解决

Release-Please 是一个流行的自动化版本管理和发布工具，广泛应用于开源项目中。近期，用户反馈在使用该工具时遇到了无法正确标记预发布版本的问题，本文将深入分析该问题的成因并提供解决方案。

问题现象

用户在使用 Release-Please 时发现，即使按照文档要求在配置文件中设置了 "prerelease": true 参数，生成的版本仍然无法被正确标记为预发布版本。具体表现为：

1. 生成的 Pull Request 没有被标记为预发布版本
2. 生成的版本号没有包含预期的 beta/alpha 等预发布标识符
3. 需要手动创建 GitHub 仓库标签才能正常工作

配置分析

Release-Please 通过 release-please-config.json 文件进行配置。正确的预发布配置应该包含以下关键参数：

{
  "prerelease": true,
  "prerelease-type": "beta",
  "versioning": "prerelease",
  "packages": {
    ".": {
      "release-type": "node",
      "include-v-in-tag": true
    }
  }
}

其中：

• prerelease: 布尔值，决定是否启用预发布
• prerelease-type: 指定预发布类型，如 beta/alpha/rc 等
• versioning: 设置为 "prerelease" 表示使用预发布版本控制策略

根本原因

经过分析，导致预发布版本标记失效的主要原因包括：

1. manifest.json 文件不完整：该文件需要包含当前版本的完整信息，包括预发布标识符。空文件或仅包含基础版本号的文件会导致预发布标记失效。

2. 工作流分离不足：当项目同时需要正式发布和预发布时，需要为两者配置独立的工作流和 manifest 文件。

3. 标签缺失：GitHub 仓库中缺少必要的标签（如 "autorelease: pending"）会导致自动化流程中断。

解决方案

1. 完善 manifest.json 文件

确保 manifest.json 包含完整的版本信息，包括预发布标识符。例如：

{
  ".": "1.0.0-beta0"
}

2. 分离正式发布和预发布工作流

对于需要同时支持正式发布和预发布的项目，建议：

1. 创建两个独立的 manifest 文件：

   • manifest-release.json：用于正式发布
   • manifest-prerelease.json：用于预发布

2. 配置对应的工作流文件，分别指向不同的 manifest 文件

3. 确保 GitHub 标签存在

在仓库设置中检查并创建以下必要标签：

• autorelease: pending
• autorelease: tagged

4. 完整配置示例

{
  "packages": {
    ".": {
      "release-type": "node",
      "include-component-in-tag": false,
      "include-v-in-tag": true,
      "versioning": "prerelease",
      "prerelease": true,
      "prerelease-type": "beta",
      "changelog-path": "CHANGELOG.md"
    }
  }
}

最佳实践

1. 版本号管理：始终在 manifest 文件中保持完整的版本号，包括预发布标识符

2. 工作流隔离：为不同环境（dev/prod）配置独立的工作流

3. 定期验证：在项目初期定期验证发布流程，确保配置正确

4. 文档参考：仔细阅读项目文档，了解所有可用配置选项的含义

通过以上措施，可以确保 Release-Please 正确生成和标记预发布版本，实现自动化版本管理的预期效果。