Go模块v2+版本必须在import路径、go.mod module声明、Git tag和本地目录结构中统一显式包含/v2，否则go get失败；三者不一致将导致版本解析错误、包找不到或类型不兼容。
必须显式在 import 路径里写 /v2，且模块定义、远程 tag、本地目录结构三者必须严格对齐，否则 go get 会失败或拉错版本。
import 路径里漏掉 /v2 就直接报错
Go 不会自动把 github.com/user/lib 解析成 v2 版本——它只认路径字面量。即使你远程仓库打了 v2.1.0 tag，只要 import 写的是 "github.com/user/lib"，Go 就当成 v0/v1 处理，然后报 invalid version: module contains a go.mod file, so major version must be compatible: should be v0 or v1, not v2。
正确写法只有这一种：
import "github.com/user/lib/v2"
常见错误包括：
立即学习“go语言免费学习笔记（深入）”；
- 只改了
go.mod里的require行，没改代码里的import - 复制粘贴时删掉了
/v2，比如从文档里抄github.com/user/lib就完事 - 以为加了
@v2.1.0后缀就能绕过路径要求，实际不行：go get github.com/user/lib@v2.1.0依然失败
go.mod 第一行 module 声明必须带 /v2
模块声明和 import 路径是绑定的。如果别人要 import 你的 v2 包，你自己的 go.mod 必须写成：
module github.com/user/lib/v2
而不是：
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
module github.com/user/lib
否则 go list -m 会识别为 v1 模块，下游 go get 时无法匹配路径。注意：
-
go mod init github.com/user/lib/v2是初始化的正确命令 - 如果已有
go.mod且内容是github.com/user/lib，直接手动改成/v2并提交，不要用go mod edit -module自动改——它可能不更新路径引用 - v3 就写
/v3，不是/v3.0.0；后缀只表示主版本层级，不是完整语义化字符串
远程 tag 和本地目录结构必须匹配 /v2
Go 拉取时会校验远程 tag 格式和本地文件系统结构。两个硬性条件缺一不可：
- Git tag 必须是完整语义化格式：
v2.0.0、v2.1.0，不能是2.0.0或v2 - 模块根目录必须是
lib/v2/（假设模块路径是github.com/user/lib/v2），不能放在lib/下再靠go.mod伪装
验证方法：
git ls-remote --tags origin | grep '^.*v2\.[0-9]\+\.[0-9]\+$'
如果没输出，说明 tag 不合规；如果本地 go.mod 在 lib/ 目录下，但路径声明是 /v2，go build 会提示 cannot find module providing package。
go get 拉不到时先清缓存再重试
旧缓存常导致 unknown revision v2.1.0，尤其之前拉过同名无版本路径的包。执行：
go clean -modcache<br>go get github.com/user/lib/v2@v2.1.0
如果用私有仓库，还要确认 GOPRIVATE 已包含对应域名，否则代理会拦截 /v2 路径请求并返回 404。另外，go mod tidy 之后检查 go.sum 是否出现两行同一域名不同路径（如 github.com/user/lib 和 github.com/user/lib/v2），那是共存正常的信号；如果只有一行且没 /v2，说明某处 still leaking v1 path。
最易被忽略的一点：v2 包里的类型和 v1 完全不兼容，哪怕字段一模一样，v1.Client 和 v2.Client 在编译器眼里是两个完全无关的类型。别指望靠 //go:replace 把 v2 路径映射回 v1——路径不一致，replace 规则压根不生效。
