go模块v2发布必须同步修改module声明、import路径和目录结构三者，缺一不可；module行须为github.com/user/repo/v2，import需显式加/v2，代码须置于v2/子目录。
Go 模块发布 v2 不是改个 tag 或 version 字段就能生效——必须同步改 module 声明、import 路径、目录结构，三者缺一不可。
go.mod 里的 module 行必须带 /v2
Go 工具链根本不看 go.mod 里的 version 字段（它甚至不合法），只认第一行 module 的路径。写 module github.com/user/repo 就永远是 v1；写 module github.com/user/repo/v2 才可能被识别为 v2。
- 路径末尾的
/v2是硬性要求，不是可选后缀 - 不能写成
/v2.0.0或/v2.x，只能是/v2 - 如果模块有子包（如
/client），完整路径应为github.com/user/repo/v2/client，不是github.com/user/repo/client/v2 - 改完后运行
go mod tidy会自动更新require中的版本，但不会碰import语句——这步得手动或脚本处理
所有 import 语句必须显式加 /v2
哪怕 go.mod 改对了，源码里还写着 import "github.com/user/repo"，编译时就会报 cannot find package "github.com/user/repo/v2"——因为 Go 按新路径找包，但你的代码没告诉它去哪导入。
- 全局搜索替换
"github.com/user/repo"→"github.com/user/repo/v2"，注意引号和斜杠 - IDE 通常不会自动更新跨模块的 import，容易漏掉内部子包引用
- 如果项目用了
vendor/，执行go mod vendor后检查vendor/github.com/user/repo/v2/是否存在，而不是只有repo/ - 错误示例：
import "github.com/user/repo"+module github.com/user/repo/v2→ 编译失败
v2 代码必须放在 v2/ 子目录且独立初始化
Go 要求 v1 和 v2 物理隔离：v1 在仓库根目录，v2 必须在 v2/ 子目录下，并在该目录内运行 go mod init github.com/user/repo/v2。混放会导致 go build 报 mismatched module。
- 目录结构必须与
module路径严格对应：路径含/v2，代码就得在v2/目录下 - 不要在根目录同时放两个
go.mod（v1 和 v2 各一个），Go 会混淆 - 打 tag 前先确认远程已有
v2.0.0：运行git ls-remote --tags origin | grep v2 - 发布命令用
go get github.com/user/repo/v2@v2.0.0，不是go get github.com/user/repo@v2.0.0（后者必然失败）
客户端引入 v2 时路径不能省略 /v2
下游项目要真正用上 v2，必须在自己的代码里写 import "github.com/user/repo/v2"，并确保 go.mod 中 require 行也带 /v2。写 import "github.com/user/repo" 永远只会拉 v1，哪怕 v2 已发布、tag 已推、路径全对。
-
go list -m all应同时显示两行：github.com/user/repo v1.5.0和github.com/user/repo/v2 v2.0.0 - 别指望
//go:replace能绕过路径约束——replace只对完全相同的 import 路径生效 - CI 环境若仍拉错版本，先跑
go clean -modcache清缓存，再试go mod download - v2 对老项目完全透明，你无法“推动”用户升级，只能靠文档明确标注导入方式
最容易被忽略的是 import 路径和目录结构的一致性：module 声明改了，import 没批量更新，或者代码没挪进 v2/ 目录，三者只要差一个，v2 就形同虚设。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
