Go模块路径必须带v2等版本后缀，因Go模块系统要求v2+主版本须显式体现在路径中以隔离不兼容变更，如module github.com/user/lib/v2对应import路径和lib/v2目录结构。
Go模块路径里为什么必须带 v2 这样的版本后缀
因为 Go 的模块系统不靠 GOPATH 或目录名推断版本，而是严格依赖模块路径本身包含版本标识。如果你写 github.com/user/lib，go 就认为这是 v0 或 v1（隐式），v2 及以上必须显式出现在路径里，否则 go get 会拒绝解析或拉错版本。
这不是可选项，是语义化版本与 Go 模块协议硬绑定的规则。背后逻辑是：不同主版本可能有不兼容变更，路径差异能天然隔离导入、避免混用。
- 错误写法：
import "github.com/user/lib"（即使实际发布了v2.1.0，go 仍当它是v1） - 正确写法：
import "github.com/user/lib/v2"，对应模块定义里的module github.com/user/lib/v2 - 模块根目录必须和路径一致：如果模块声明是
github.com/user/lib/v2，那它不能放在lib/目录下，而应放在lib/v2/
go get 拉 v2+ 包时总报 unknown revision
常见于你本地没清理旧缓存，或远程仓库 tag 格式不合规。Go 要求 v2+ 的 tag 必须是 v2.0.0、v2.1.0 这种完整语义化格式，2.0.0 或 2.x 都不行。
- 检查远程 tag：
git ls-remote --tags origin | grep v2 - 确认
go.mod第一行是module github.com/user/lib/v2，不是.../lib - 清除本地缓存：
go clean -modcache，再试go get github.com/user/lib/v2@v2.1.0 - 如果用私有仓库，确保
GOINSECURE或GOPRIVATE已配好，否则v2+路径可能触发代理校验失败
同一个项目里同时用 v1 和 v2 版本的同一包是否可行
可以，而且正是这套机制的设计目的：通过路径区分实现共存。Go 不会把 github.com/user/lib 和 github.com/user/lib/v2 当成同一个模块。
立即学习“go语言免费学习笔记（深入）”；
- 导入时路径不同，编译器就视为两个独立包，类型不兼容（比如
v2.Client和v1.Client不能互赋值） - 注意
go list -m all会显示两个条目，各自锁定自己的版本 - 别指望用
//go:replace把v2替换成v1路径——路径不匹配会导致 import 错误，替换只对「完全相同路径」生效 - 升级时建议分步：先引入
v2并迁移部分代码，等全量切完再删掉v1导入，避免混淆
发布 v3 包时，路径写 /v3 还是 /v3.0.0
只写 /v3。版本后缀是路径层级，不是版本号字符串。模块路径里 v3 表示“主版本三”，所有 v3.x.y 的发布都共享这个路径。
- 模块定义必须是
module github.com/user/lib/v3，不是.../v3.0.0 - 打 tag 用
v3.0.0、v3.1.0，但路径永远止步于/v3 - 如果某天要发
v4，就得新建目录lib/v4/，改go.mod为module github.com/user/lib/v4，再推新 tag - 别省略
v3直接写/v4——中间跳版会导致路径断裂，旧代码无法平滑升级
最易被忽略的是目录结构和 go.mod 声明的一致性：路径多一个 v2，代码就得在 v2/ 子目录里，少一个就编译失败。这不是命名习惯，是 Go 模块加载器的硬约束。
