如何使用npm semantic-release管理Beta版本？解决版本生成异常

场景说明 #

仓库包含两个分支：

• main：生产分支，当前标签为v0.7.0-beta
• develop：开发测试分支，当前标签为v0.7.0-betaDev
  版本规则：develop始终领先main（如main为v0.7.0时，develop为v0.7.1）
  预期行为：

1. develop合并到main后，main版本同步为develop的版本（如v0.7.1）
2. 分支对应预发布标签正常生效

当前问题：GitHub Actions中使用semantic-release时，系统提示无可用发布版本，自动生成v1.0.0版本。现有package.json配置如下：

"release": {
  "branches": [{"name": "main"},{"name": "develop", "prerelease": true}],
  "npmPublish": false,
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/npm",
    ["@semantic-release/github", {
      "successComment": false,
      "failComment": false,
      "releasedLabels": false
    }],
    [
      "@semantic-release/git",
      {
        "assets": [],
        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
      }
    ]
  ]
}

核心原因 #

1. 标签命名不符合SemVer规范，semantic-release无法识别现有版本，只能从头生成v1.0.0
2. develop分支预发布标识未明确指定，和现有标签不匹配
3. 分支版本关联逻辑配置缺失

修复步骤 #

1. 统一标签命名规范 #

semantic-release遵循SemVer规范，预发布版本格式必须为主版本号.次版本号.修订号-预发布标识.序号（如v0.7.0-beta.1），先清理旧标签并重新创建：

# 删除本地+远程不符合规范的标签
git tag -d v0.7.0-betaDev
git push origin :refs/tags/v0.7.0-betaDev
git tag -d v0.7.0-beta
git push origin :refs/tags/v0.7.0-beta

# 重新创建符合规范的标签
git checkout main
git tag v0.7.0-beta.1
git push origin v0.7.0-beta.1

git checkout develop
git tag v0.7.1-betaDev.1
git push origin v0.7.1-betaDev.1

2. 调整semantic-release配置 #

明确指定develop分支的预发布标识，确保和标签匹配：

"release": {
  "branches": [
    "main",
    {
      "name": "develop",
      "prerelease": "betaDev" // 和标签中的预发布标识保持一致
    }
  ],
  "npmPublish": false,
  "plugins": [
    "@semantic-release/commit-analyzer",
    "@semantic-release/release-notes-generator",
    "@semantic-release/npm",
    ["@semantic-release/github", {
      "successComment": false,
      "failComment": false,
      "releasedLabels": false
    }],
    [
      "@semantic-release/git",
      {
        "assets": [],
        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
      }
    ]
  ]
}

3. 优化合并逻辑 #

合并develop到main时，确保包含semantic-release自动生成的chore(release)提交记录，这样工具才能识别develop的版本号，直接将main升级到对应正式版本（如v0.7.1）。

4. 验证CI权限与触发规则 #

• 确认GitHub Actions的token拥有repo权限，可操作标签和发布
• 确保工作流在分支推送、PR合并时正常触发

关键提示 #

semantic-release完全依赖符合规范的标签和Angular风格提交信息（feat/fix/chore等前缀）判断版本升级，不符合规则的内容会被直接忽略，导致版本从头生成。

内容的提问来源于stack exchange，提问作者JesusMF23