多版本共存是 go 模块的默认行为，非 bug；模块按需解析，mvs 算法仅在冲突不可调和时报错；需通过 go mod graph 和 go mod why 定位版本引入路径；replace 仅影响当前模块 import 解析；v2+ 版本必须带 /v2 路径才能共存。
多版本共存不是 bug，是 Go 模块的默认行为
Go 允许同一模块（如 github.com/some/lib）在 go list -m all 中出现多个版本，只要它们没被同一个构建图同时“强制统一”。这不是配置错误，而是模块系统按需解析的结果：每个模块只认自己 require 的版本，MVS（最小版本选择）算法只在冲突不可调和时才报错。
真正需要干预的信号很明确：cannot use ... as ... value in argument to（类型不匹配）、interface conversion: ... is X, not Y（运行时 panic）、或 go mod tidy 报 inconsistent dependencies。看到 go list -m all 里有重复模块名，先别急着删——它可能完全不影响构建。
怎么确认哪个模块拉入了哪个版本？
关键不是看列表，而是追溯路径。用这两条命令组合定位源头：
-
go mod graph | grep 'some-lib'：列出所有引入some-lib的直接依赖及其指定版本 -
go mod why -m github.com/some/lib@v1.5.0：输出从main开始、经过哪些 import 路径最终选中该版本
如果某第三方库（比如 github.com/other/tool）内部硬编码依赖 v2.0.0+incompatible，而你的主模块 require v1.2.0，go mod graph 会清楚显示这条边，go mod why 则能告诉你为什么 v2 被选中——这才是决策依据。
replace 不是全局替换，它只覆盖 import 解析
replace 只改变当前模块内 import 语句的解析目标，不会阻止其他模块拉入自己的版本。常见误用：
- 写
replace github.com/some/lib => github.com/some/lib v1.5.0，但github.com/other/tool仍会按自己go.mod的require拉v2.0.0，结果还是两个版本并存，且可能因 API 不兼容导致 panic - 用
replace github.com/some/lib => ./local-fix调试后忘记删，CI 构建失败（路径不存在） - 替换成 fork 分支，却没同步上游关键 fix，导致安全漏洞漏检
正确做法：优先执行 go get github.com/some/lib@v1.5.0 显式升级主模块的 require 行，再跑 go mod tidy，让 MVS 重新计算整个图——它比手动 replace 更可靠，也更易复现。
v2+ 版本必须带 /v2 路径，否则无法共存
Go 不允许 github.com/some/lib v1.2.0 和 github.com/some/lib v2.0.0 同时存在，除非后者路径是 github.com/some/lib/v2。这是硬性规则，不是建议：
- 错误写法：
module github.com/some/lib+require github.com/some/lib v2.0.0→invalid version: module contains a go.mod file, so major version must be compatible - 正确写法：
module github.com/some/lib/v2，且所有导入必须写import "github.com/some/lib/v2"
所以当你看到两个版本“无法共存”，第一反应不是降级或 replace，而是检查那个 v2+ 版本是否真的发布了带 /v2 的模块路径。没改路径就发 v2 tag，等于主动制造冲突。
