如何处理Go vanity URL及主版本子包的模块解析问题

问题根源 #

你的问题本质是Go语义化版本规则中，v2及以上主版本的模块必须满足两个核心要求：

• 模块路径必须以/vN（N≥2）结尾
• 对应版本的代码中go.mod的module声明必须与该路径完全匹配
  同时Vanity URL的配置需要正确映射带/vN后缀的路径到仓库的对应子目录。

具体解决方案 #

1. 调整仓库结构与go.mod配置 #

• 在仓库根目录创建v2子目录，将v2版本的所有代码移入该目录
• 修改v2/go.mod中的module声明，改为：

  module tomasruud.github.io/gvm/v2
  
  go 1.xx // 替换为你的实际Go版本
  

• 同步调整v2代码内部的导入路径（比如原本导入tomasruud.github.io/gvm/pkg的地方，要改为tomasruud.github.io/gvm/v2/pkg）

2. 正确打版本标签 #

找到v2子目录代码对应的提交ID，在仓库中打v2版本标签：

git tag v2.0.0 <commit-id>
git push origin v2.0.0

注意：标签名必须严格遵循v2.x.x格式，不能省略前缀v

3. 配置Vanity URL的v2路径映射 #

在你的Vanity URL服务器上，针对路径/gvm/v2添加Go模块导入元数据：

<!DOCTYPE html>
<html>
<head>
    <!-- 针对v2版本的导入声明，指定仓库路径与子目录 -->
    <meta name="go-import" content="tomasruud.github.io/gvm/v2 git https://github.com/tomasruud/gvm?dir=v2">
</head>
<body>
    Go module: tomasruud.github.io/gvm/v2
</body>
</html>

根路径/gvm的原有元数据保持不变，用于v0/v1版本的解析。

验证命令 #

完成上述配置后，执行以下命令测试：

go get tomasruud.github.io/gvm/v2@v2.0.0

错误原因复盘 #

• 不添加v2条目时：Go尝试拉取tomasruud.github.io/gvm@v2.0.0，但根目录的go.mod模块路径不带/v2，违反v2+版本的路径规则，因此报错。
• 添加v2条目但未调整子目录与go.mod时：Go拉取到的v2.0.0版本代码中，go.mod的模块路径还是tomasruud.github.io/gvm，与请求的tomasruud.github.io/gvm/v2不匹配，因此报错。

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