Go模块v2必须通过路径/v2声明，而非仅版本号；需修改module路径、import语句、代码目录结构，并确保物理隔离，否则将导致版本冲突或编译失败。
go get 无法拉到 v2 版本？检查模块路径是否带 /v2 后缀
Go 工具链根本不识别 github.com/user/repo@v2.0.0 这种写法——它只在模块路径末尾有 /v2 时才认为这是 v2 模块。不改路径，go get 再怎么指定版本也只会去根目录找 tag，自然报 unknown revision v2.0.0。
- 必须把
go.mod里的module github.com/user/repo改成module github.com/user/repo/v2 - 所有
import语句同步更新：从"github.com/user/repo"改为"github.com/user/repo/v2" - v2 代码必须放在
v2/子目录下（或其它带版本号的子目录），且该目录内要独立运行go mod init github.com/user/repo/v2 -
replace不能绕过路径规则：本地用replace github.com/user/repo => ./v2可能暂时编译通过，但下游go get github.com/user/repo仍会拉错，go list -m all也会显示路径不一致
升级后编译失败或类型不匹配？确认 v1 和 v2 是否物理隔离
v1 和 v2 共存不是靠分支或 tag 切换，而是靠文件系统级隔离。混放会导致 go build 无法判断该用哪个版本，甚至报 cannot load ...: ambiguous import。
- v1 代码留在仓库根目录，
go.mod中仍是module github.com/user/repo - v2 代码严格放在
v2/目录下，该目录有自己的go.mod（声明module github.com/user/repo/v2）和完整代码树 - 不要把 v2 的代码复制进根目录、也不要让 v2 目录里残留 v1 的
go.mod或go.sum - CI 构建前建议加一步：
go list -m all | grep repo，确保输出里只有github.com/user/repo或github.com/user/repo/v2，不能两者同时出现
依赖树里既有 v1 又有 v2？用 go mod graph 定位“偷偷拉旧版”的包
即使你主模块已切 v2，只要某个间接依赖（比如 pkgA）还在 import github.com/user/repo（无后缀），Go 就会把它当 v1 加进来，最终导致两个版本共存冲突。
- 执行
go mod graph | grep github.com/user/repo，看哪些包引入了无后缀路径 - 对每个结果跑
go mod why -m github.com/user/repo，查清调用链：是pkgA直接 import，还是pkgB依赖了pkgA才间接引入 - 如果
pkgA是你可控的内部模块，直接改它的 import 路径；如果是第三方库，只能等它发新版，或临时replace它的依赖（但注意replace不传递给下游） - 别指望
go mod tidy自动清理这种跨版本引用——它只管 require 行，不管 import 语句是否合法
升级后运行时 panic 或行为异常？重点检查 interface 实现和函数签名
v2 升级往往伴随 API 割裂：方法被删、参数顺序变、返回值结构改。这类问题不会在编译时报错（尤其用了 interface），而是在运行时才暴露。
立即学习“go语言免费学习笔记（深入）”；
- 翻 v2 的 CHANGELOG，重点关注
Breaking changes部分，逐条核对你的调用点 - 搜索代码中所有对该模块的
func调用和struct初始化，确认参数个数、类型、顺序是否匹配 - 特别留意
context.Context参数是否被插入到首位、error 返回是否从第二个位置移到最后、struct 字段是否被重命名或移除 - 测试不能只跑
go test ./...，要包含真实 HTTP 请求、数据库交互等集成路径——很多兼容性问题只在 runtime 环境触发
