Go模块v2+升级必须同步更新import路径为/v2，因Go将不同版本视为独立模块；module路径、本地目录结构和import语句三者须严格一致，否则编译报错。
Go 模块主版本升级（v2+）不是改个 go.mod 里的 module 行就完事——所有 import 路径必须同步带 /v2，否则编译直接报 cannot find package。
为什么 import 路径必须加 /v2
Go 把 github.com/user/repo 和 github.com/user/repo/v2 视为两个完全独立的模块。不加后缀，Go 就找不到你放在 /v2/ 目录下的代码；加了但 import 没改，源码里还在找旧路径，自然报错。
- 模块路径后缀和本地目录结构必须严格一致：
module github.com/user/repo/v2→ 代码必须在仓库根目录下的/v2/子目录中 -
v0和v1不强制后缀，但v2+是硬性要求，不是风格建议 - 即使只改了
go.mod，没动import，go build仍会失败
如何批量更新 import 路径
go mod tidy 只修 go.mod 里的 require，不会碰源码中的 import。这步必须手动或脚本处理，漏一处就编译不过。
- 用 IDE 的全局替换最稳妥：把
"github.com/user/repo"替换为"github.com/user/repo/v2"，注意引号和斜杠方向 - 子包也要同步改：比如
"github.com/user/repo/client"→"github.com/user/repo/v2/client" - 内部相对导入（如
./pkg）不受影响，只改绝对导入路径 - 如果项目用了
replace指向本地路径，记得检查replace行是否还匹配新路径
常见错误现象与定位方式
编译失败时别急着删 go.sum 或清缓存——先确认是不是 import 路径没改全。
立即学习“go语言免费学习笔记（深入）”；
- 错误信息典型是：
import "github.com/user/repo" not found或cannot find module providing package github.com/user/repo/v2/pkg - 运行
go list -m all | grep repo看实际加载的是哪个模块路径 -
go mod graph | grep repo能暴露依赖图里混用了 v1 和 v2 路径 - 如果某个文件能编译、另一个不能，大概率是那个文件的
import漏改了
旧版本用户为什么不会自动升级
v2 对 v1 用户完全不可见——他们 go get github.com/user/repo 拿到的永远是 v1，除非显式写 @v2。你没法“推送升级”，只能靠文档、README 提示、或双版本并存过渡期。
-
go get github.com/user/repo@v2.0.0才会拉 v2，且要求本地 import 已更新 - 如果 v1 还在维护，建议在 v1 分支继续发
v1.x补丁，避免破坏存量用户 - CI 中可加检查：扫描所有
.go文件，确保没有残留的github.com/user/repo（不含/v2）导入
最易被忽略的点：v2 代码必须物理放在 /v2/ 目录下，不是靠 replace 或 go mod edit 绕过去就能糊弄编译器的。路径、目录、import，三者必须咬死一致。
