go模块v2+版本必须在import路径末尾加/v2，否则仍视为v1；go.mod中module路径、仓库目录结构、tag命名均需匹配/v2，客户端导入也必须显式使用/v2路径。
Go模块v2+版本必须在import路径末尾加/v2
不加/v2路径，Go会认为你发布的还是v1，即使go.mod里写的是v2.0.0。这是语义化版本在Go里的硬性约定，不是可选项。
常见错误现象：go get example.com/mylib@v2.0.0 报错 unknown revision v2.0.0 或直接拉到v1分支；或者拉下来后import "example.com/mylib" 仍指向v1代码，完全没走v2逻辑。
- 路径必须显式包含
/v2，比如example.com/mylib/v2，对应仓库里v2/子目录（或主干的v2分支） - 模块根目录的
go.mod文件第一行必须是module example.com/mylib/v2，不能是example.com/mylib - 如果用GitHub托管，打tag要带
v2.0.0前缀，但路径和go.mod里的/v2才是Go识别版本的关键，tag只是辅助
同一仓库共存v1和v2需要分目录或分分支
Go不允许在同一个go.mod路径下发布多个主版本，所以v1和v2不能都放在仓库根目录——否则v2的go.mod会覆盖v1的导入路径，导致v1使用者go get失败。
使用场景：你维护一个已广泛使用的v1模块，现在要发布不兼容的v2，又不想废弃v1。
立即学习“go语言免费学习笔记（深入）”；
- 推荐做法：把v2代码放进
v2/子目录，该目录下有独立的go.mod，内容为module example.com/mylib/v2 - 另一种做法：用
v2分支，分支根目录放go.mod，内容同样是module example.com/mylib/v2 - 不要在根目录同时放v1和v2的
go.mod，Go工具链会混淆，go list -m all可能报mismatched module
客户端导入v2时路径必须带/v2，且不能省略
调用方写import "example.com/mylib/v2"才是正确的，写import "example.com/mylib"永远只能拿到v1，哪怕v2已发布、tag已打、go.mod也改了。
参数差异：v1和v2对客户端来说是两个完全不同的模块，Go会分别下载、缓存、构建，互不影响。
- 升级时不能只改
go.mod里的require版本号，必须同步改所有import语句中的路径 - IDE通常不会自动帮你改import路径，容易漏掉某个文件，导致编译报
undefined: xxx（其实是用了v1的API，但v2里删了或改名了） -
go get example.com/mylib/v2@v2.1.0是合法命令；但go get example.com/mylib@v2.1.0会失败或静默降级到v1
go mod tidy不会自动修正import路径
go mod tidy只管依赖树和go.mod一致性，它不管源码里写的import是不是匹配当前require的版本。也就是说，就算你require了example.com/mylib/v2 v2.1.0，但代码里还写着import "example.com/mylib"，tidy也不会报错或提醒。
性能影响：这种错配会导致编译通过但运行时panic，或者调用到v1里已被移除的函数——因为Go在构建时按import路径找包，而不是按require版本。
- 检查方式：
grep -r 'import.*"example.com/mylib"' ./ --include="*.go"，确认是否全为/v2结尾 - CI里建议加一条检查：
go list -f '{{.ImportPath}}' ./... | grep '^example.com/mylib$'，如果有输出就说明存在未升级的v1 import - 最易忽略的点：内部工具脚本、测试文件、甚至
examples/目录下的代码，常常被遗忘升级
