Go模块v2+必须将go.mod中module行改为带/v2后缀的路径，否则工具链不识别为v2；同时需同步更新所有import语句、将代码移至v2/子目录，并打v2.0.0 tag。
go.mod 里 module 行必须带 /v2 后缀
不改 module 行，v2 就不算正式发布。Go 工具链只认路径里的 /v2 作为主版本标识，而不是 tag 名或本地目录名。比如你打了 v2.0.0 tag，但 go.mod 还是 module example.com/lib，那 go get example.com/lib@v2.0.0 会报 unknown revision v2.0.0 或 invalid version。
常见错误：只改 Git tag，没动 go.mod；或者写了 module example.com/lib/v2，但实际模块根目录仍是 lib/ 而非 lib/v2/。
-
go mod init example.com/lib/v2是安全起点（如果从头建 v2） - 已有 v1 模块升级时，直接编辑
go.mod第一行，把module example.com/lib改成module example.com/lib/v2 - 改完后运行
go mod tidy，它会自动修正依赖树中对该模块的引用（但不会改你代码里的import）
import 路径和磁盘目录结构必须严格一致
Go 不靠 GOPATH 推断路径，而是把 import 字符串当真实文件系统路径解析。如果你写 import "example.com/lib/v2"，Go 就会去 $GOPATH/pkg/mod/cache/download/example.com/lib/v2@v2.1.0 或你本地 ./lib/v2 找代码。路径不匹配，go build 直接失败：cannot find module providing package。
典型坑：改了 go.mod 和 import，但忘了重命名本地目录。比如原项目在 lib/，v2 应该挪到 lib/v2/，否则 go list -m 能看到模块，但 go build 报找不到包。
立即学习“go语言免费学习笔记（深入）”；
- 本地开发时，先
mkdir lib/v2，再把所有源码（包括go.mod）移进去 - 所有内部
import语句也要同步更新：比如"example.com/lib/handler"→"example.com/lib/v2/handler" - CI/CD 流水线里如果用
go mod download，确保远程仓库的v2.0.0tag 对应的是lib/v2/目录下的代码，不是根目录
go get 拉 v2+ 包失败的三个高频原因
go get example.com/lib/v2@v2.1.0 失败，90% 情况下不是网络问题，而是本地状态或远端配置不对。
- 本地缓存残留旧版本：运行
go clean -modcache再试，尤其当你反复改过go.mod或 tag - Git tag 格式非法：远程必须有
v2.1.0（带v前缀），不能是2.1.0、v2或v2.1；用git ls-remote --tags origin | grep v2确认 - 私有仓库未配
GOPRIVATE：如果模块在 GitHub private repo 或 GitLab，得加export GOPRIVATE="example.com/*"，否则代理会拦截/v2路径校验
v1 和 v2 能共存，但类型完全不兼容
路径不同 = 完全独立模块。你可以同时 import "example.com/lib" 和 "example.com/lib/v2"，go list -m all 会显示两行，各自锁定版本。但这不意味着能混用类型。
比如 v1 的 Client 和 v2 的 Client 是两个不同类型，哪怕字段一模一样，也不能赋值、传参或类型断言。
- 迁移时别指望用
//go:replace把 v1 替成 v2 路径——replace 只对完全相同的 import path 生效，example.com/lib≠example.com/lib/v2 - 升级建议分步：先引入 v2 并封装适配层，等旧逻辑逐步迁出后再删 v1 import
- 如果项目里大量用
example.com/lib，又想快速试 v2，可临时在go.mod加replace example.com/lib => example.com/lib/v2 v2.1.0，但仅限测试，上线前必须改 import
/v2 —— 无论是 go.mod、import、目录、tag 还是 GOPRIVATE 配置 —— 都会导致不可预测的加载失败。 
