v2+模块必须改import路径，因为Go只认导入语句本身，import "github.com/user/repo"与import "github.com/user/repo/v2"被视为两个不同模块；v2+是显式版本，路径必须含/v2，否则不被识别为合法v2模块。
为什么 v2+ 模块必须改 import 路径
Go 不会根据 go.mod 里写的 module github.com/user/repo/v2 就自动把旧 import 改成带 /v2 的路径。它只认导入语句本身——import "github.com/user/repo" 和 import "github.com/user/repo/v2" 是两个完全不同的模块，哪怕代码一模一样。
常见错误现象：你打了 v2.0.0 tag、改了 go.mod 第一行，但其他项目仍用旧路径 import "github.com/user/repo"，结果编译报错：require github.com/user/repo: version "v2.0.0" invalid: module contains a go.mod file, so major version must be compatible: should be v0 or v1, not v2。
- 根本原因：工具链发现 import 路径没带
/v2，却要求拉取 v2 版本，直接拒绝 - v0 和 v1 是隐式版本：路径不带后缀，默认按 v0（开发中）或 v1（稳定）处理
- v2+ 是显式版本：路径必须含
/v2，否则不被识别为合法 v2 模块 - IDE 或
go list -m all显示的模块名也必须和 import 路径一致，否则无法 resolve
如何正确发布一个 v2 模块
不是打个 tag 就完事。v2 发布是一组同步动作，漏掉任何一步都会导致下游无法使用。
- 在模块根目录，把
go.mod第一行改成module github.com/user/repo/v2 - 所有内部
import语句全部更新：比如import "github.com/user/repo/utils"→import "github.com/user/repo/v2/utils"（包括_test.go文件） - Git 打 tag 必须是
v2.0.0（不能是2.0.0、release/v2或v2） - 对外文档、README 中的 import 示例也要同步改成带
/v2的路径 - 旧 v1 保持原路径
github.com/user/repo不变，两者可长期共存
go get @v2.0.0 失败的典型原因
go get github.com/user/repo@v2.0.0 报错，基本就卡在这几个点上：
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
立即学习“go语言免费学习笔记（深入）”；
- 远程仓库没打
v2.0.0tag，或者 tag 名字不对（缺v前缀、大小写混用如V2.0.0） - 本地
go.mod还是module github.com/user/repo，没改成/v2 - 用户执行的是
go get github.com/user/repo@v2.0.0，但正确命令应是go get github.com/user/repo/v2@v2.0.0 - 模块已发布，但未推送到公开可访问的 Git 服务（如私有 GitLab 未配置 proxy 或权限限制）
注意：go list -m -versions github.com/user/repo 只列出符合 v\d+\.\d+\.\d+ 格式的 tag，不会显示分支或 commit —— 如果它没列出来 v2.0.0，说明 tag 根本没生效。
伪版本和预发布版本的陷阱
不符合 SemVer 格式的 tag（比如 1.2.3、v1.2.x、v1.2.3+2023）会被 Go 当作伪版本处理，形如 v1.2.3-0.20230405123456-abcdef123456。这种版本无法被 @v2.0.0 显式引用，且 MVS 算法可能选错依赖版本。
- 预发布版本如
v2.0.0-beta.1合法，但go get -u默认不升级到它；@latest也不会选它 -
+metadata部分（如v1.2.3+incompatible）会被 Go 完全忽略，仅incompatible是特例，表示该模块未启用 modules - v0.x.y 属于不稳定阶段，不承诺兼容性；v1.x.y 才是正式稳定版起点
主版本号变更这件事，本质不是“升级”，而是“新建一个模块”。路径改了，import 改了，tag 对了，才是完整的 v2。
