go模块v2+必须修改import路径为带版本后缀的形式，否则工具链无法加载对应版本；正确路径如github.com/user/repo/v2，且需同步更新所有引用、tag规范、goprivate配置及本地replace指向。
Go 模块 v2+ 必须改 import 路径，否则根本不会加载到 v2 代码 —— 这不是可选项，是 Go 工具链的硬性校验规则。
go get github.com/user/repo@v2.0.0 总报 unknown revision
这是最典型的路径错配现象：Go 命令会去 github.com/user/repo 这个路径下找 tag v2.0.0，但实际它只存在于 github.com/user/repo/v2 下。
- 正确命令必须带完整路径：
go get github.com/user/repo/v2@v2.0.0 - 确认远程仓库已打合规 tag：
git ls-remote --tags origin | grep '^.*v2\.[0-9]*\.[0-9]*$'（v2.0.0合法，2.0.0或v2不合法） - 本地缓存可能干扰解析：
go clean -modcache再重试 - 私有仓库需检查
GOPRIVATE是否包含github.com/user/repo/v2，否则代理层会拒绝解析带后缀的路径
import "github.com/user/repo" 编译通过，但实际用的还是 v1
路径没改，Go 就永远把它当 v0/v1。即使你本地 go.mod 已改成 module github.com/user/repo/v2，只要 import 语句仍是旧路径，编译器就按旧路径去找包 —— 自然找不到，或 fallback 到 v1 的缓存。
-
go mod tidy不会修改任何import语句，这步必须手动或用脚本批量替换 - 所有子包引用也要同步更新，例如
github.com/user/repo/client→github.com/user/repo/v2/client - 测试文件、example 文件、
internal/包里对本模块的引用，同样要改路径 - 如果用了
//go:embed或//go:generate，注意它们不依赖 import 路径，但生成逻辑可能隐式依赖老版本结构
同一个项目里同时用 v1 和 v2 版本的同一模块
可以，而且正是这套路径机制的设计目的：不同路径 = 不同模块 = 类型系统隔离。
-
github.com/user/repo和github.com/user/repo/v2在go list -m all中是两条独立记录 - v1 的
Client和 v2 的Client类型完全不兼容，不能互相赋值或传参 - 不要试图用
replace把github.com/user/repo/v2指向本地./根目录 —— 路径不匹配会导致import解析失败 - 若需本地开发调试 v2，应
replace github.com/user/repo/v2 => ./v2，且确保v2/目录下有独立的go.mod，其中module行为github.com/user/repo/v2
发布 v3 时路径写 /v3 还是 /v3.0.0
只写 /v3。路径后缀是主版本层级标识，不是版本字符串。
- 模块路径中
/v3表示“主版本三”，所有v3.x.y发布都共享该路径 - 对应 tag 仍用
v3.0.0、v3.1.0等标准语义化格式 - 别在路径里塞小版本号，比如
/v3.1是非法的，Go 工具链会拒绝识别 - v3 代码必须放在
v3/子目录，且该目录下go.mod的module行必须为github.com/user/repo/v3
最容易被忽略的是：路径变更不是“发布动作”，而是“导入契约”。一旦 v2 路径对外暴露，所有下游用户的 import 语句就必须跟着改 —— 否则他们永远拿不到你的 v2，也看不到你写的 breaking change 文档里强调的那些新行为。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
