go模块v2+版本必须在import路径中显式添加/v2后缀，否则工具链无法识别，导致go get失败、import报错、ci构建不一致；go.mod、import路径和git tag三者必须严格一致，且@latest不会跨主版本升级。
Go 模块里写错 v2 版本，不是编译报错那么简单——它会让工具链根本“看不见”你发布的 v2 代码，go get 失败、import 报错、CI 构建不一致，全是因为没按语义导入版本规则来。
为什么 v2+ 必须在 import 路径里加 /v2
这不是风格问题，是 Go 工具链硬性识别逻辑：路径 github.com/user/lib 和 github.com/user/lib/v2 在 Go 看来是两个完全不同的模块，哪怕代码一模一样。不加 /v2，go build 就不会去查 v2 的 go.mod 或源码。
-
go.mod里写module github.com/user/lib/v2，但import "github.com/user/lib"→ 编译失败，提示import path doesn't contain version或cannot find module providing package - 发布 tag 是
v2.0.0，但go get github.com/user/lib@v2.0.0会失败；必须用go get github.com/user/lib/v2@v2.0.0 -
v0和v1可省略路径后缀，因为它们被隐式识别；v2+没有例外，不加就是无效
go.mod、import 路径、Git tag 三者必须严格对齐
任意一处错位，依赖就断掉。Go 不靠“猜”，只认三者字符串完全一致的匹配。
-
go.mod第一行必须是module github.com/user/lib/v2（不能少/v2） - 所有
.go文件里的import必须是import "github.com/user/lib/v2/xxx"（包括测试、子包、内部引用） - Git tag 必须是
v2.0.0（开头带v，不能是2.0.0或release/v2） - 私有仓库还要确认 tag 是 public 的，lightweight tag 不会被
go list -m -versions列出
@latest 和 @v2.0.0 的行为差异很关键
@latest 不等于“最新版”，它只取当前主版本下最新稳定版，且绝不会跨主版本升级——这是很多人线上出问题的根源。
-
go get example.com/pkg@latest→ 如果远程有v1.12.3和v2.0.0，它只会拉v1.12.3（因 import 路径仍是example.com/pkg） -
go get example.com/pkg/v2@latest→ 这才可能拉到v2.1.0，前提是路径已切到/v2 -
@latest在 CI 中不可靠：今天拉v1.9.0，明天远程发了v1.9.1，构建结果就变了；生产环境应避免 - 想锁死版本？用
go get example.com/pkg@v1.9.0+go mod tidy，否则go get -u可能悄悄升 patch 或 minor
怎么验证你真的用上了 v2
别信 go.mod 里写的，要查工具链最终选中的版本和路径。
- 运行
go list -m all | grep lib→ 看输出是不是github.com/user/lib/v2 v2.1.0（带/v2才对） - 运行
go mod graph | grep lib→ 查哪个依赖项在拉这个模块、用了什么版本 - 全局搜索项目里所有
import "github.com/user/lib"，漏改一个文件，整个构建就崩 - 如果
go list -m all显示的是github.com/user/lib v2.1.0+incompatible，说明路径没改，还在走兼容模式，v2 功能实际不可用
最常被忽略的一点：v2 路径变更不是“发布时做一次”，而是从 go.mod、所有 import、Git tag 到下游用户的引用方式，全部同步切换。任何环节脱节，都会让 v2 变成“看不见的版本”。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
