go模块v2+必须显式在module路径中包含/v2，如module github.com/user/pkg/v2；否则下游引用github.com/user/pkg/v2会失败，因v2是独立模块而非v1升级。
Go模块v2+路径必须显式声明module名含/v2
Go不支持自动升级主版本，v2不是后缀而是模块路径的一部分。如果你写了module github.com/user/pkg，哪怕代码是v2，go mod仍认为它是v1——下游引用github.com/user/pkg/v2会报unknown revision或no matching versions。
正确做法：v2代码的go.mod第一行必须是module github.com/user/pkg/v2，且该路径要和你实际发布的tag（如v2.0.0）完全匹配。
- 发布前检查：
git tag v2.0.0→git push origin v2.0.0，确保远程有对应tag - 本地调试时，可用
go get github.com/user/pkg/v2@v2.0.0验证是否可拉取 - 别在v2分支里留着
module github.com/user/pkg，那是最常见“看着对、实际错”的坑
同一仓库多版本共存需独立分支或目录隔离
Go要求不同主版本模块路径不同，所以v1和v2不能共用同一份go.mod。常见错误是把v2代码直接塞进v1分支，结果go list -m all里只看到v1，v2根本不可见。
可行方案只有两种：
- 推荐：为v2建独立分支（如
main-v2），其go.mod为module github.com/user/pkg/v2，tag打在该分支上 - 或使用目录方式：根目录放v1，
/v2子目录放v2代码，其go.mod仍为module github.com/user/pkg/v2（注意不是github.com/user/pkg/v2/v2） - 千万别用
replace在v1的go.mod里硬指v2路径——这仅本地有效，别人go get时失效
go get引用v2模块时路径末尾/v2不能省
即使你的模块叫github.com/user/pkg，v2版本也必须用完整路径github.com/user/pkg/v2导入。写import "github.com/user/pkg"永远只会解析到v1（或最新无版本后缀的版本）。
错误现象：编译报undefined: SomeV2Func，但你确认函数存在——大概率是import路径没带/v2。
- 所有
import语句、go get命令、require行都必须显式含/v2 -
go get github.com/user/pkg@v2.0.0会失败，必须写go get github.com/user/pkg/v2@v2.0.0 - ide自动补全常忽略
/v2，要手动检查并修正
v2模块无法直接升级v1的go.sum记录
v1和v2是两个完全独立模块，go.sum里它们的校验和互不干扰。当你把依赖从github.com/user/pkg切到github.com/user/pkg/v2，旧的sum行不会被覆盖或删除，新行会追加。
这本身不是问题，但容易掩盖真实依赖关系：
- 运行
go mod tidy后，v1的require行若未手动删掉，会残留无用记录 -
go list -m all | grep pkg可能同时显示v1和v2，说明有隐式间接依赖未清理 - CI构建时若缓存了旧
go.sum，可能因校验和不匹配失败，此时需go clean -modcache再试
主版本变更本质是创建新模块，不是“升级”。路径、分支、tag、import、require——五处必须同步一致，漏一处就断链。很多人卡在“为什么我打了v2 tag却拉不到”，其实只是go.mod里少了个/v2。