这是最典型的重复定义信号，go mod graph 显示同一模块被多个路径引入，说明不同依赖各自锁定了不兼容版本，go 通过 mvs 算法选一个生效版本，但可能与代码实际需要的 api 不匹配。
go mod graph 显示同一模块被多个路径引入
这是最典型的重复定义信号。比如 go mod graph 输出里出现两行都含 github.com/sirupsen/logrus@v1.8.1，但来源不同：一行来自 pkgA，另一行来自 pkgB，说明它们各自锁定了不兼容的版本。Go 不会加载两个版本，而是用 MVS 算法选一个——但选出来的可能不是你代码实际需要的。
这时别急着删 go.sum 或重 init。先定位谁在拉旧版：
-
go mod graph | grep 'logrus@'查所有引用路径 -
go list -m -f '{{.Path}} {{.Version}}' all | grep logrus看最终选中的是哪个版本 -
go mod why -m github.com/sirupsen/logrus追完整调用链，确认是不是测试工具（如ginkgo）或 linter（如staticcheck）偷偷带进来的
replace 后 go build 仍用旧版本
replace 生效有硬性前提：它必须写在主模块的 go.mod 里，且路径完全匹配（大小写、斜杠方向都不能错），写完后必须跟 go mod tidy。否则 go build 仍可能从缓存或 go.sum 里取旧版。
常见漏操作：
- 写了
replace github.com/sirupsen/logrus => github.com/sirupsen/logrus v1.9.3，但没运行go mod tidy，go.sum没更新 - 本地路径 replace（如
=> ./fixes/logrus）提交到了 CI，而 CI 机器上该路径不存在，直接构建失败 - 同一模块被多个
replace声明覆盖（比如一个指向 fork，另一个指向本地），Go 会报错：multiple replacements for module
go list -m all 显示多个校验和但只用一个版本
go.sum 里出现同一模块多个 hash，是正常现象——说明它曾被不同版本间接引用过。但最终运行时只加载一个版本，由 MVS 决定。问题在于：你 import 的代码，可能按 v1.8.1 的 API 写的，但实际加载的是 v1.9.3，而后者删了某个方法，导致 cannot use X as type Y。
验证是否真用了你想要的版本：
- 运行
go list -m -f '{{.Path}} {{.Version}}' all | grep logrus，输出应和replace目标一致 - 检查
go.mod中是否有// indirect注释的 require 行；如果有且你依赖它的行为，就删掉注释，让它变成显式 require，提升优先级 - 如果仍不对，执行
go clean -modcache清掉本地缓存，再go mod tidy重拉
exclude 某个版本后构建失败
exclude 是高危操作，仅在确认某版本存在严重 bug 且无法升级上游时使用。它不是“忽略”，而是“禁止加载”——如果某个依赖明确 require v1.5.0，而你 exclude v1.5.0，Go 就找不到满足条件的版本，直接报错 no version of ... satisfies ...。
慎用场景：
- 只 exclude 已知崩溃的 patch 版本（如
v1.2.3），不要 exclude 整个 minor（如v1.2.0） - exclude 后必须跑
go list -m all确认其他版本能被选中 - CI 流程里避免用 exclude；它不传递给下游，别人 clone 你的 repo 可能构建失败
真正难处理的不是怎么加 replace 或 exclude，而是判断该不该加——很多冲突其实源于某个间接依赖升级后破坏了接口，但没人改对应的调用方。这种时候，go mod why 和 go test ./... 比任何命令都管用。
