go mod tidy 是依赖图的重算引擎，按最小版本选择（MVS）规则自动推导各模块版本，而非保留手动指定版本；冲突源于 require 声明与实际依赖约束不一致，升级或降级是 MVS 必然结果。
go mod tidy 不是修复工具，它是依赖图的“重算引擎”——它不会听你的话去“保留 v1.2.0”，而是按最小版本选择（MVS）规则重新推导整个图中每个模块该用哪个版本。所谓“冲突”，本质是你写的 require 和实际依赖图的约束不一致。
为什么 go mod tidy 会悄悄升级/降级你的依赖？
这不是 bug，是 MVS 的必然行为。比如你手动 go get github.com/some/pkg@v1.5.0，但某个子依赖（如 github.com/other/tool）只兼容 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 生效前提是它写在主模块的 go.mod 文件里，且路径必须完全匹配（包括大小写、斜杠方向）。它不阻止其他版本被间接引入，但它确保你代码里 import "github.com/some/pkg" 解析到的是你指定的目标。
- 指向特定 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声明（比如不同 commit），Go 会报错，需手动清理
避免 invalid indirect / ambiguous import 的关键操作
类型不一致错误（如 cannot use X as type Y）往往是因为同一个包名被两个不同版本加载——例如 golang.org/x/net 的 v0.14.0 和 v0.17.0 同时存在。这时 go mod graph 和 go list -m all 是唯一直观依据。
- 先清点实际加载的版本：
go list -m -f '{{.Path}} {{.Version}}' all | grep 'golang.org/x/net' - 定位引入路径：
go mod graph | grep 'golang.org/x/net@' - 若发现测试工具（如
ginkgo）或 linter（如staticcheck）偷偷拉了旧版，可考虑：
– 升级该工具本身
– 用exclude显式禁用冲突版本：exclude golang.org/x/net v0.14.0
– 或临时删掉go.sum+go mod tidy重建（仅限调试，勿提交）
go mod edit -require 是比手写 require 更安全的写法
直接编辑 go.mod 添加 require github.com/some/pkg v1.5.0 可能被 go mod tidy 删除（如果它判断该版本不被任何路径需要）。而 go mod edit -require=github.com/some/pkg@v1.5.0 会强制保留在 go.mod 中，并触发重算。
- 执行后检查是否生效：
go list -m github.com/some/pkg应返回v1.5.0 - 如果报错
used for two different module paths，说明有 fork 镜像（如gitee.com/xxx/pkg）混入，需统一源地址 - 搭配
go mod why github.com/some/pkg确认该 require 是否真被主模块逻辑依赖，避免冗余锁定
真正难处理的从来不是命令怎么敲，而是当 go mod graph 显示 5 层嵌套、7 条路径都指向同一个模块的不同 vX.Y.Z 时，你得判断哪条路径的约束是刚性的、哪条可以协商——这没有银弹，只有反复 go mod why + 尝试 replace + 看测试是否过。别信“一键解决”，信日志和路径。
