go模块版本路径（如/v3）生效依赖go.mod中module声明与导入路径严格一致，而非目录名自动识别；_v2等下划线写法是gopath时代遗留，module模式下应避免。
Go module 导入路径里带 _v2 或 /v3 是怎么生效的
Go 并不靠目录名自动识别版本，而是靠模块路径（module 声明）和导入路径是否匹配。你看到的 _v2 目录或 /v3 子路径，本质是开发者手动维护的模块路径别名，不是 Go 的“内置规则”。
比如：github.com/user/lib/v3 能被正确导入，前提是该目录下 go.mod 文件第一行写的是：module github.com/user/lib/v3。如果只是把代码挪进 v3/ 目录但没改 go.mod，Go 会直接报错：cannot find module providing package。
- 模块路径必须和
import语句完全一致（包括大小写、斜杠、vN后缀） -
_v2这种下划线写法是旧版 hack，仅在 GOPATH 模式下偶有出现，module 模式下应避免——它不会被 Go 工具链识别为版本标识 - 如果你看到别人用了
lib_v2目录，十有八九是历史遗留，且大概率依赖replace或本地go mod edit -replace才能跑通
为什么 go get github.com/user/lib/v3 有时拉不到最新 commit
因为 Go 默认只拉 tagged 版本（如 v3.1.0），不会自动拉 v3 分支的 HEAD。即使你刚 push 了新代码到 v3 分支，go get 也不会感知，除非打 tag 或显式指定 commit。
- 想强制拉分支最新：用
go get github.com/user/lib/v3@main（前提是v3目录的go.mod正确声明了该路径） - 更常见的是打轻量 tag：
git tag v3.2.0 && git push origin v3.2.0，然后go get github.com/user/lib/v3@v3.2.0 - 如果模块路径是
github.com/user/lib，但你import了github.com/user/lib/v3，Go 会当作两个完全独立模块处理——它们的依赖、缓存、构建结果互不影响
go mod tidy 报 require github.com/user/lib/v3: version "v3.0.0" invalid
这是典型的版本号格式错误。Go 要求 vN 系列模块的 tag 名必须严格匹配 vN.x.y 格式（注意开头小写 v），不能是 V3.0.0、3.0.0、v3-rc1 或 v3.0.0-beta。
立即学习“go语言免费学习笔记（深入）”；
- 检查 tag 是否存在且命名规范：
git tag --list | grep v3 - 如果 tag 错了，删掉重打：
git tag -d v3.0.0 && git push origin :refs/tags/v3.0.0，再git tag v3.0.0 && git push origin v3.0.0 - 如果还没发布正式版，可用伪版本号绕过，例如：
v3.0.0-20240520143211-abcdef123456（由go mod graph或go list -m -versions可查到） - 注意：
go mod tidy不会自动帮你选 tag，它只按go.sum和go.mod中已写死的版本去校验
同一仓库内维护 v1、v2、v3 多个版本目录的现实代价
这不是“只要建好目录就能用”的功能，而是要同步维护多个 go.mod、多套 CI 流程、多条 release 分支，稍有疏忽就会导致版本错乱或依赖污染。
- 每个版本目录必须有独立
go.mod，且module行不能复用主仓库路径（比如主仓库是github.com/user/lib，那v3/go.mod必须写module github.com/user/lib/v3） - 无法共用
internal/包：因为v2和v3是不同模块，internal的可见性边界按模块划分，跨模块引用会编译失败 - CI 构建时容易漏测某个版本目录，尤其是
v2还在维护但没人碰了，某次重构意外破坏了它却没发现
真正难的不是写对路径，而是让所有人（包括自己三个月后的脑子）始终记得：哪个分支对应哪个模块路径、tag 有没有推、go.mod 有没有手误多敲一个空格。
