Semantic-release无法为NPM包生成新版本问题求助

问题描述 #

将NPM包从旧仓库迁移至新仓库后，Semantic Release无法生成新版本，仅提示：
The local branch main is behind the remote one, therefore a new version won't be published.
已在新仓库创建与已发布版本匹配的v1.0.0标签，且移除了changelog.md以重新开始，使用的Semantic Release配置如下：

{
  "branches": ["main"],
  "plugins": [
    [
      "@semantic-release/commit-analyzer",
      {
        "preset": "conventionalcommits"
      }
    ],
    "@semantic-release/release-notes-generator",
    "@semantic-release/changelog",
    [
      "@semantic-release/npm",
      {
        "npmPublish": false
      }
    ],
    [
      "@semantic-release/github",
      {
        "assets": [
          "CHANGELOG.md",
          "dist/*",
          "package.json"
        ]
      }
    ],
    [
      "@semantic-release/git",
      {
        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
      }
    ]
  ]
}

解决步骤 #

1. 确保CI拉取完整仓库历史 #

GitHub Actions的默认checkout仅拉取最新单个提交，Semantic Release需要完整历史和标签来判断版本。修改checkout配置：

- name: Checkout code
  uses: actions/checkout@v4
  with:
    fetch-depth: 0  # 拉取完整仓库历史
    fetch-tags: true  # 拉取所有标签

2. 同步本地与远程分支状态 #

在本地执行命令，确保main分支与远程完全同步：

git fetch origin
git checkout main
git reset --hard origin/main

若迁移后分支历史存在差异，需确保新仓库main分支包含旧仓库必要提交历史，或重新推送正确分支历史到新仓库。

3. 验证标签关联提交的正确性 #

检查v1.0.0标签是否关联到新仓库main分支的正确提交：

git show v1.0.0

若标签关联提交不在main分支，重新创建标签：

git tag -d v1.0.0  # 删除旧标签
git tag v1.0.0 <正确的提交哈希>  # 关联到正确提交
git push origin v1.0.0 --force  # 推送新标签到远程

4. 确认分支配置一致性 #

检查branches配置与远程分支名称匹配（当前为main无需修改），若远程分支为master则调整配置中的分支名。

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