go mod tidy 不解决冲突，仅按MVS规则重算依赖图；它会回退你手动写的版本以满足所有依赖约束，如require v1.5.0但子依赖只支持v1.3.0时自动降级。

go mod tidy 不会“解决”冲突，它只按最小版本选择（MVS）规则重算依赖图；所谓“彻底解决”，本质是让 MVS 选出来的版本符合你的运行或编译预期。

为什么 go mod tidy 总是悄悄改掉你写的版本

这不是 bug，是 MVS 的必然行为：它忽略你在 go.mod 里手动写的 require 行，而是从整个依赖图出发，找出所有路径都能接受的最低兼容版本。比如你写 require github.com/some/pkg v1.5.0，但某个子依赖只声明支持 v1.3.0，go mod tidy 就会回退到 v1.3.0。

• 查谁在拉低版本：go mod graph | grep 'some/pkg@'
• 看约束来源：go list -m -f '{{.Path}}: {{.Require}}' all | grep some/pkg
• 确认最终版本：go list -m -json all | jq -r 'select(.Path == "github.com/some/pkg") | .Version'

replace 不是万能钥匙，但它是唯一可控的干预手段

replace 只影响你代码中 import 的解析路径，不阻止其他版本被间接引入——它只是“重定向”，不是“删除”。生效前提是写在主模块的 go.mod 里，且路径完全匹配（大小写、斜杠方向都不能错）。

• 指向特定 tag：replace github.com/some/pkg => github.com/some/pkg v1.5.0
• 指向本地修复版：replace github.com/some/pkg => ./fixes/some-pkg
• 执行后必须跟 go mod tidy，否则 go build 可能仍用缓存旧版
• 同一模块不能有多个 replace 声明，否则 Go 直接报错

exclude 能禁用问题版本，但仅限于你不直接 require 的情况

exclude 是真正“移除”某版本的机制，但它只对间接引入的版本有效；如果你自己 require 了某个版本，再 exclude 它，Go 会报错。

• 适用场景：某个测试工具（如 ginkgo）偷偷拉了已知 crash 的 golang.org/x/net v0.14.0，而你主模块没直接依赖它
• 写法：exclude golang.org/x/net v0.14.0
• 验证是否生效：go list -m all | grep 'golang.org/x/net' 应不再出现该版本
• 注意：exclude 不影响 go.sum 中已有校验和，重建时需配合 go mod tidy

多版本共存不是错误，但 interface mismatch 才是真问题

Go 允许同一模块多个版本共存，只要它们不互相暴露不兼容的类型。真正出问题的是：两个不同版本的包被同时加载，导致类型断言失败、方法签名不一致等编译错误。

• 定位源头：go mod why -m github.com/some/pkg@v1.5.0
• 检查是否多版本并存：go list -m all | grep 'some/pkg'
• 确认 go.sum 是否含多个校验和条目（说明历史曾加载过多个版本）
• 临时清理环境（仅调试）：rm go.sum && go mod tidy，但切勿提交空 go.sum

最常被忽略的一点：replace 指向本地路径时，CI 构建必然失败；exclude 对主模块自己的 require 无效；而 go mod graph 输出里带 @ 的行才是真实生效的版本约束——别只盯着 go.mod 里的 require 行。