Go模块多版本共存报错本质是间接依赖引入不兼容版本，需用go get指定统一版本并go mod tidy清理；major版本升级须更新import路径；replace仅限本地且需同步go.sum；私有仓库需配置GOPRIVATE和认证。
go.mod 中出现 require 多版本共存报错
Go 1.11+ 启用 module 后，go build 或 go list 报类似 ambiguous import: found package xxx in multiple modules，本质是不同依赖间接引入了同一包的不兼容版本（比如 github.com/sirupsen/logrus v1.8.1 和 v1.9.3），而 Go 拒绝自动选边。
解决核心是让 go mod 显式降级或升级到统一版本：
- 运行
go mod graph | grep 'logrus'查看谁拉入了哪个版本 - 用
go get github.com/sirupsen/logrus@v1.9.3强制指定所需版本（会写入go.mod的require块） - 再执行
go mod tidy清理未使用的旧版本引用 - 若某依赖硬编码调用了 v1.8.1 特有 API，而 v1.9.3 已移除，需联系该依赖作者或 fork 修复
主模块升级 major 版本后下游包无法构建
例如你的项目从 github.com/xxx/lib v1 升级到 v2（路径含 /v2），但某个间接依赖仍 import github.com/xxx/lib（无 /v2），Go 会认为这是两个完全不同的包，导致类型不兼容、函数找不到等错误。
这不是“冲突”，而是 Go 的语义化导入路径规则在起作用：
立即学习“go语言免费学习笔记（深入）”；
- major 版本 ≥ v2 必须体现在 import 路径末尾，如
github.com/xxx/lib/v2 - 不能靠
replace把v2映射回v1路径——这会让类型系统失效 - 正确做法：确认所有直接/间接依赖是否已适配 v2；未适配则需
replace到其 fork 后的兼容分支，或暂时锁定主模块回退到 v1 -
go list -m all | grep xxx可快速定位哪些模块还在用旧路径
使用 replace 临时绕过冲突但 CI 失败
replace 在本地有效，但 CI 构建时可能因 GOPROXY 或缓存机制忽略它，或因 go mod verify 校验失败而中断。
关键点在于 replace 的作用域和持久性：
-
replace只影响当前 module，不会传递给依赖它的其他 module - 若被 replace 的包本身有
go.sum记录，且你改了源码但没更新 checksum，go build会拒绝运行 - CI 中应确保执行
go mod download+go mod verify，并检查go.sum是否包含你 replace 后的新校验值 - 更稳妥的做法：将 fix 提交到上游，或发布一个带 patch tag 的新版本（如
v1.2.3-fix-logging），然后go get它
私有仓库包拉取失败导致 go mod tidy 卡住
常见于公司内网 GitLab 或 GitHub Enterprise，go mod tidy 报 unknown revision 或 401 Unauthorized，本质不是版本冲突，而是认证/路由问题，但它会阻断整个依赖解析流程，看起来像“冲突”。
必须先打通拉取链路，才能继续处理版本逻辑：
- 配置
~/.gitconfig中对应域名的insteadOf规则，把 HTTPS 替换为 SSH（如url."git@git.example.com:".insteadOf "https://git.example.com/"） - 设置环境变量
GOPRIVATE=git.example.com/*，让 Go 跳过 proxy 和 checksum 校验 - 若用 SSH，确保
ssh-agent已加载对应密钥，且git ls-remote git@git.example.com/xxx能通 - 避免在
go.mod中硬写replace指向本地路径——这会让 CI 完全不可重现
版本冲突背后往往混着路径规范、认证机制、校验逻辑三层问题。真正卡住人的，常常不是“选哪个版本”，而是某个 replace 没生效、某个 go.sum 没更新、或者私有域名没加进 GOPRIVATE ——这些细节不显眼，但缺一不可。
