Go Modules大版本>2时小版本的发布与使用问题

问题原因分析 #

1. 第一个报错go: module tssgit.reyrey.com/teschste/go-httpmailer@upgrade found (v2.1.0+incompatible), but does not contain package tssgit.reyrey.com/teschste/go-httpmailer/v3：
   Go模块解析器默认会从仓库根路径查找版本，而你的仓库根路径存在未遵循Modules规范的v2兼容版本，该版本不包含v3路径下的包，导致解析失败。

2. 第二个报错go: tssgit.reyrey.com/teschste/go-httpmailer/v3@v3.1.0: invalid version: go.mod has non-.../v3 module path "tssgit.reyrey.com/teschste/go-httpmailer/v3.1" (and .../v3/go.mod does not exist) at revision v3.1.0：
   你发布的v3.1.0版本中，go.mod的module声明错误地写成了/v3.1，违反了Go Modules规则——v3及以上大版本的模块路径必须以/vN（N为大版本号）结尾，小版本升级不能修改这个后缀。

解决步骤 #

1. 修复私有库v3.1.0版本的模块声明 #

• 切换到私有库v3.1.0版本的代码，确保go.mod中的module声明为：

  module tssgit.reyrey.com/teschste/go-httpmailer/v3
  

  绝对不能写成module tssgit.reyrey.com/teschste/go-httpmailer/v3.1。
• 修正后重新推送版本tag：

  # 删除本地错误tag
  git tag -d v3.1.0
  # 删除远程错误tag
  git push origin :v3.1.0
  # 重新打tag并推送
  git tag v3.1.0
  git push origin v3.1.0
  

2. 清理本地模块缓存 #

执行以下命令清除本地缓存的错误模块信息，避免干扰后续拉取：

go clean -modcache

也可以删除项目根目录下的go.sum文件，后续拉取时会自动重新生成。

3. 正确拉取v3.1.0版本 #

使用指定版本的命令拉取：

go get tssgit.reyrey.com/teschste/go-httpmailer/v3@v3.1.0

4. 额外检查项 #

• 确保私有库v3.1.0版本的所有内部导入路径都使用/v3后缀，例如导入子包时应写tssgit.reyrey.com/teschste/go-httpmailer/v3/subpackage，而非带v3.1的路径。
• 确认本地Go版本为1.13及以上，该版本后Go Modules对v2+版本的支持才稳定。

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