go.mod中只改module路径无效，必须同步更新所有import语句为/v2路径、将代码移至v2/子目录并独立初始化模块，否则编译失败且版本不可见。
go.mod 里只改 module 路径根本没用
很多人升级 v2 时，只把 go.mod 第一行从 module github.com/user/repo 改成 module github.com/user/repo/v2，然后就以为完事了。结果 go build 直接报 cannot find package "github.com/user/repo/v2"——Go 根本没去读你改的路径，它按 import 语句去找包，而你的代码里还是 import "github.com/user/repo"。
真正生效的不是 go.mod 的 module 声明，而是所有 import 语句和磁盘目录结构的一致性。模块路径后缀是 Go 解析版本的唯一依据，不是装饰。
-
go.mod中的module行必须带/v2 - 所有同模块内的
import必须同步改成带/v2的完整路径（包括子包，如github.com/user/repo/v2/client） - v2 代码必须放在
v2/子目录下，且该目录内要独立运行go mod init github.com/user/repo/v2 - 别用
replace在本地绕过路径——下游用户go get时仍会拉错版本
为什么 go get github.com/user/repo@v2.0.0 总失败
这个命令注定失败：Go 工具链默认只在 github.com/user/repo 这个路径下找 tag，而 v2.0.0 实际打在 github.com/user/repo/v2 对应的 v2/ 子目录里。路径不匹配，自然找不到 revision。
正确写法只有两种：
-
go get github.com/user/repo/v2@v2.0.0（用完整模块路径） -
go get ./v2（如果当前在仓库根目录，且v2/下有合法go.mod）
注意：执行前必须确保已 git tag v2.0.0 并 git push origin v2.0.0，且 tag 是打在 v2/ 目录所在 commit 上，不是根目录。
同一仓库同时维护 v1 和 v2 的物理隔离要求
v1 和 v2 不是“分支切换”就能共存的东西。Go 要求它们在文件系统层面严格分离：
- v1 代码留在仓库根目录，
go.mod是module github.com/user/repo - v2 代码必须挪进
v2/子目录，该目录下有独立的go.mod（module github.com/user/repo/v2） - 不能靠
replace把根目录代码“映射”到/v2路径——构建时会因导入路径冲突直接失败 -
go list -m all输出中，github.com/user/repo和github.com/user/repo/v2会作为两个不同模块并存，互不影响
混放会导致 go build 随机选错包、go mod tidy 误删依赖、CI 构建结果不可复现。
import 语句批量更新最容易漏掉的三类地方
手动全局替换 "github.com/user/repo" → "github.com/user/repo/v2" 很快，但以下位置常被忽略：
- 测试文件里的
import（尤其是xxx_test.go中引用本模块的路径） - 嵌套子模块的内部 import，比如
v2/pkg/foo里还 import 了github.com/user/repo/internal/util，这个也要改成github.com/user/repo/v2/internal/util - 第三方工具生成的代码（如 protobuf 编译出的
.pb.go文件），它们的 import 通常硬编码，需手动或脚本修正
建议用 grep -r 'import.*"github.com/user/repo"' . --include="*.go" 扫一遍，再逐个确认是否已加 /v2。别信 go mod tidy 会帮你修 import——它只管 go.mod 和 go.sum，不管源码。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
