Go模块v1和v2共存需将二者视为不同模块：v2必须声明为module github.com/user/lib/v2，代码中import "github.com/user/lib/v2"，go.mod中分别require github.com/user/lib v1.9.3和require github.com/user/lib/v2 v2.3.0。
go.mod 中如何声明 v1 和 v2 两个主版本共存
Go 模块系统允许同一库的 v1 和 v2 并存，前提是它们被识别为**不同模块路径**。关键不是“让 Go 加载两个版本”，而是让两个版本在 import 路径上天然隔离。
比如你要同时用 github.com/sirupsen/logrus v1.9.3 和它的 v2.x 版本，必须满足：
- v2 版本的模块路径已显式声明为
github.com/sirupsen/logrus/v2（注意末尾/v2） - 你的代码里 import 时也写成
"github.com/sirupsen/logrus/v2"，而不是去掉/v2 -
go.mod中需存在两行独立的require：require ( github.com/sirupsen/logrus v1.9.3 github.com/sirupsen/logrus/v2 v2.3.0 ) - 不能靠
replace github.com/sirupsen/logrus => github.com/sirupsen/logrus/v2强行映射——这会破坏模块校验，go.sum会报错
为什么 go list -m all 显示多个版本不等于冲突
go list -m all 输出中出现同一个模块名多次（如 github.com/some/lib v1.5.0 和 github.com/some/lib/v2 v2.1.0），只是说明构建图里存在两个逻辑上不同的模块——Go 把它们当两个包处理，完全合法。
真正要警觉的是以下信号：
- 编译失败，提示
cannot use ... as ... in argument to（类型不匹配） - 运行时 panic：
interface conversion: interface {} is X, not Y -
go mod tidy报inconsistent dependencies或require ... version "vX.Y.Z" invalid -
go.sum里同一模块路径对应多个校验和，且 commit hash 不同（说明本地缓存或 proxy 混入了非 tag 提交）
replace 不是解决多版本共存的手段，而是临时绕过
replace 的作用是重写 import 解析路径，它不会消除版本冲突，只是掩盖表层问题。典型误用：
- 写
replace github.com/old/lib => github.com/myfork/lib v1.8.0后，所有import "github.com/old/lib"都指向 fork，但某第三方依赖硬编码用了github.com/old/lib v2.0.0+incompatible，仍可能触发 panic - 本地用
replace github.com/foo => ./local-fix调试完没删，CI 构建直接失败（路径不存在） - 替换成一个未同步 upstream 安全补丁的 fork，线上跑着带漏洞的老代码
正确做法：优先执行 go get github.com/old/lib@v1.8.0 + go mod tidy，让 MVS 算法自动协调；只有确认上游无响应、且你控制所有调用点时，才用 replace 打补丁，并加注释标明临时性。
大版本升级时，模块路径和 import 路径必须同步改
v2+ 升级不是改个 tag 就完事。必须三步同步：
- 在新分支里修改
go.mod的 module 声明，加上/v2（如module example.com/mymodule/v2） - 所有调用方代码里的 import 路径也要加
/v2（"example.com/mymodule/v2"） - 发布时打规范 tag：
v2.0.0，而非v2.0.0+incompatible
漏掉任意一步，Go 就无法区分 v1 和 v2，要么降级失败，要么类型混用导致 runtime panic。尤其注意：旧代码若仍 import 无 /v2 的路径，它只会看到 v1 版本，哪怕你本地已装 v2 —— import 路径才是唯一权威标识。
