Go模块v2+必须在module路径中显式添加/v2等主版本后缀，且路径需与/v2子目录结构严格一致，所有import语句须同步更新为带/v2的完整路径，否则编译失败或版本不可见。
Go模块路径必须包含主版本号后缀
Go官方要求v2+模块必须在module声明中显式带上/v2、/v3等后缀，否则go get会拒绝解析或降级为v0/v1。这不是可选项，是模块语义版本（SemVer）在Go生态里的硬性落地规则。
- 错误写法：
module github.com/user/repo→ 升级到v2后，所有依赖它的项目仍会拉取v1分支，根本不会感知v2存在 - 正确写法：
module github.com/user/repo/v2→ v2代码必须放在独立的/v2子目录下（如github.com/user/repo/v2/pkg） - 路径后缀和本地目录结构必须严格一致：模块路径
/v2对应仓库内/v2/子目录，不能靠replace硬绕过
go.mod里不能只改module路径就完事
单纯把module行改成/v2，不调整导入路径和依赖引用，会导致编译失败——Go会按新路径去找包，但源码里还是用老路径import "github.com/user/repo"，自然报cannot find package。
- 所有
import语句必须同步更新：把"github.com/user/repo"全换成"github.com/user/repo/v2" - 如果项目里有内部子包（如
github.com/user/repo/client），也要变成github.com/user/repo/v2/client -
go mod tidy会自动修正require中的版本，但不会动import语句，这步必须手动或脚本批量处理
旧版本用户不会自动升级，要主动兼容或通知
v2模块对v1使用者完全透明：他们go get github.com/user/repo拿到的永远是v1，除非显式写@v2。你无法“强制升级”，只能靠文档、breaking change提示、或者双版本并存过渡。
- 想平滑过渡？保留v1分支继续维护，同时发布v2分支，并在README顶部加醒目标注
- 不想维护两套？在v1的
go.mod里加// +build ignore注释或直接归档v1标签，但需提前邮件/issue告知下游 - CI里建议加检查：
grep -r "github.com/user/repo$" ./... | grep -v "/v2"，防遗漏旧导入
go get @v2失败常见原因
执行go get github.com/user/repo/v2@v2.1.0报错，大概率不是网络问题，而是模块发布姿势不对。
立即学习“go语言免费学习笔记（深入）”；
- 仓库根目录没有
go.mod？不行。v2模块的go.mod必须在/v2/go.mod，且内容为module github.com/user/repo/v2 - 打了
v2.1.0tag，但没推送到origin？go get只认远程tag，本地tag无效 - 用了
git subtree或submodule导致/v2/目录实际不存在？Go不会解包再找，路径必须真实存在 - 错误信息如
invalid version: module contains a go.mod file, so major version must be compatible→ 检查go.mod里是不是漏写了/v2后缀
版本路径这件事，看着只是多敲几个字符，但路径错一位、目录少一层、import漏一个斜杠，整个模块就对外不可见。它不难，但容错率极低。
