v2+模块必须带/v2路径，因为go将模块路径本身作为版本标识，是硬性规则而非可选约定；若module声明未含/v2，go get会拒绝解析或降级为v1，且路径须与/v2子目录结构严格一致，所有import语句也必须同步更新为带/v2的完整路径。
为什么v2+模块必须带/v2路径
Go 把 module 路径本身当作版本标识，不是可选约定，是硬性规则。你发布 v2.0.0，Go 就要求模块路径必须写成 module github.com/user/repo/v2，否则 go get 会拒绝解析或直接降级到 v1。
常见错误现象：go get github.com/user/repo@v2.0.0 失败，提示 unknown revision v2.0.0 或 invalid version；或者成功拉取但项目里仍 import "github.com/user/repo"，编译报 cannot find package。
- 路径后缀必须和本地目录结构严格一致：代码得放在
/v2/子目录下，不能靠replace硬绕过 -
go mod tidy不会帮你改 import 语句，它只管依赖图，不管源码里的字符串 - v1 和 v2 是两个完全独立的模块，同一项目里可以共存，但 import 路径不同，不能混用
升级时 import 语句怎么批量改
所有 import 必须从 "github.com/user/repo" 改成 "github.com/user/repo/v2"，包括内部子包，比如 "github.com/user/repo/client" → "github.com/user/repo/v2/client"。
手动逐个改容易漏，尤其在多层嵌套或 vendor 场景下。推荐用脚本或 IDE 的全局替换，注意避开注释和字符串字面量：
- 用
grep -r 'github.com/user/repo"' --include='*.go' .先确认所有引用点 - 用
sed -i '' 's|github.com/user/repo"|github.com/user/repo/v2"|g' **/*.go（macOS）或sed -i 's|github.com/user/repo"|github.com/user/repo/v2"|g' $(grep -rl 'github.com/user/repo"' --include='*.go')（Linux） - 改完立刻
go build，别等go mod tidy后再验——路径错的话 tidy 也救不回来
go get -u 为什么升不到 v2
go get -u 默认只升 minor/patch，不会跨 major。它看到已 require v1.9.3，就只找 v1.x.x 里最新的，哪怕远程已有 v2.0.0，它也当不存在。
想升 v2，必须显式指定路径和版本：
-
go get github.com/user/repo/v2@v2.0.0—— 拉指定 tag -
go get github.com/user/repo/v2@latest—— 拉 v2 分支下最新 semver tag（不是 master） -
go get github.com/user/repo/v2@master不推荐，可能锁定到未打 tag 的不稳定 commit - 执行后必须跟
go mod tidy，否则间接依赖可能没对齐
v2模块对老用户完全透明
v2 不会自动影响 v1 用户。他们 go get github.com/user/repo 拿到的永远是 v1，除非显式写 @v2 或改 import 路径。
这意味着你无法“强制升级”，只能靠文档、breaking change 提示，或双版本并存过渡。容易被忽略的一点是：go.sum 里 v1 和 v2 的校验和完全独立，哪怕它们共享部分代码，哈希也不同，不能复用。
CI/CD 中如果用了 go mod tidy -e 忽略错误，可能掩盖因路径不匹配导致的 fetch 失败，最终构建卡在 missing module 阶段。
