go mod tidy 按最小版本选择（mvs）规则重算依赖图，不保留手动指定版本；若间接依赖仅兼容旧版，会强制降级；replace 仅重定向 import 解析路径，require 删除 // indirect 可提升版本优先级；go.sum 多校验和表明多版本共存，但仅 mvs 选中版本被加载。
go mod tidy 会按最小版本选择（MVS）规则重算整个依赖图，它不保留你手动写的版本号——所谓“下载版本不对”，本质是你的 require 声明和实际依赖约束不匹配，不是下载错了，而是选错了。
为什么 go mod tidy 总是拉低或跳过你想要的版本
这不是网络或缓存问题，而是 MVS 算法在执行：只要某个间接依赖（比如测试工具、linter 或底层库）只兼容 v1.3.0，而你手动写了 require github.com/some/pkg v1.5.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 => ./local-fix - 写完必须跟
go mod tidy，否则go build可能仍用缓存旧版 - CI 环境中禁止提交本地路径
replace，否则构建失败
require + 删除 // indirect 是提升优先级的有效手段
当某个间接依赖的行为变化影响你（比如 golang.org/x/net 的 HTTP/2 实现变更），而你又没法改它的直接引用者时，可以把它变成“显式依赖”：
- 运行
go get github.com/problematic/pkg@v1.2.3，它会自动加require行并带// indirect注释 - 手动删掉该行末尾的
// indirect，让 MVS 把它当高优先级约束处理 - 再跑
go mod tidy，它会以这个版本为锚点重新推导 - 副作用：其他依赖后续升级可能再次触发版本变动，需持续观察
go.sum 出现多个校验和说明多版本共存已发生
如果 go.sum 里同一个模块有多个 hash 条目（如 github.com/some/pkg v1.3.0 和 v1.5.0 各有一行），证明不同路径确实引入了不同版本——但 Go 只会加载其中一个（MVS 选中的那个）。此时编译报错 cannot use X as type Y，往往是因为两个版本的类型定义不兼容。
- 先用
go list -m -f '{{.Path}} {{.Version}}' all | grep some/pkg确认当前实际加载的是哪个 - 再用
go mod why -m github.com/some/pkg@v1.3.0追溯是谁引入的 - 若发现是
ginkgo或staticcheck这类开发工具拉的旧版，考虑升级该工具本身，而非硬扛
真正难处理的不是版本选错，而是多个模块对同一包的 API 使用方式存在隐性差异——这种冲突不会在 go mod tidy 阶段暴露，要到编译或运行时才浮现。排查时别只盯着 go.mod，得把 go mod graph 和 go list -m all 的输出对照着看，才能看清谁在悄悄改规则。
