Go模块迁移后旧版本标签报错：路径声明与引用不符问题排查

问题场景 #

将私有代码仓库从GitLab SaaS迁移至自建版本后，完成以下操作：

• 把仓库a的Go模块路径从old.com/workspace/a更新为new.com/workspace/a，为最新提交打上标签v1.2.3-new，仓库b引用该版本执行go mod tidy验证正常
• 为了让仓库b能引用原old.com/workspace/a的旧版本，检出仓库a的旧标签，修改模块路径为new.com/workspace/a后打上v1.1.1-new标签，但仓库b引用该版本时出现报错：

go: new.com/workspace/a@v1.1.1-new: parsing go.mod: module declares its path as: old.com/workspace/b but was required as: new.com/workspace/b

已确认v1.1.1-new标签对应的go.mod中模块路径已正确设置为module new.com/workspace/a，但问题依旧。

排查与解决办法 #

1. 确认标签与提交的正确性 #

• 登录自建Git仓库后台，找到仓库a的v1.1.1-new标签，检查其指向的提交中go.mod的module声明是否确实是new.com/workspace/a
• 如果标签错误绑定了未修改模块路径的旧提交，按以下步骤修正：

  # 本地删除错误标签
  git tag -d v1.1.1-new
  # 远程删除错误标签
  git push origin :refs/tags/v1.1.1-new
  # 检出目标旧版本的提交哈希
  git checkout <原旧标签对应的提交ID>
  # 修改go.mod的module字段为new.com/workspace/a
  git add go.mod
  git commit -m "update module path for legacy version"
  # 重新打标签并推送
  git tag v1.1.1-new
  git push origin v1.1.1-new
  

2. 清理本地Go模块缓存 #

Go的模块缓存可能残留了旧版本的错误信息，执行命令清理：

# 清理全部模块缓存
go clean -modcache
# 或仅清理目标模块的指定版本缓存
go clean -modcache new.com/workspace/a@v1.1.1-new

3. 绕过模块代理直接拉取（若使用代理） #

如果环境配置了Go模块代理，代理可能未同步自建仓库的最新标签，可临时禁用代理验证：

GOPROXY=direct go get new.com/workspace/a@v1.1.1-new

4. 重置仓库b的依赖状态 #

在仓库b中，删除go.sum文件后重新整理依赖，避免残留旧路径的校验信息：

rm go.sum
go mod tidy

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