Go 依赖升级后仍命中旧版本：用 go list -m all 还原 MVS 选择结果

依赖升级后，go.mod 里明明改成了更高版本，构建却仍然命中旧版本，先别急着反复执行 go get。Go Modules 使用最小版本选择（MVS）：每个模块的 require 是最低要求，Go 会沿着完整模块图追踪每个模块被要求的最高版本，最后形成 build list。真正参与构建的是这份列表，而不是某一行文字。

本文围绕一个具体排障结果展开：从当前 build list 找到“谁抬高了版本”，再区分可用升级、replace、exclude 和 go.work 的影响。完成后，你应能解释版本选择，而不是只记住一个命令。

先看 build list：为什么 require 不是最终版本

假设主模块直接依赖模块 A 和模块 B，A 要求模块 C 至少为 v1.3.0，B 要求 C 至少为 v1.4.0。即使主模块只写了 C 的旧间接要求，MVS 也会选择模块 C 的 v1.4.0，因为它必须同时满足两条依赖边。

先在包含 go.mod 的目录执行：

go list -m all
go list -m -json all

第一条适合快速扫读，第二条适合看 Path、Version 和 Replace 字段。官方文档把 build list 定义为构建会使用的模块版本集合；它不是单独保存的 lock 文件，而是在模块感知命令开始时由 MVS 计算。

用三组命令定位是谁抬高了版本

第一组看结果：

go list -m all | rg 'example.com/codec'
go list -m -u all | rg 'example.com/codec'

第一条告诉你当前选中了什么；第二条在有可用更新时，会把候选版本显示在当前版本旁边。若当前版本比你预期的高，第二组回到依赖边：

go mod graph | rg 'example.com/codec'
go mod why -m example.com/codec

go mod graph 适合找出哪个模块提出了更高的最低要求，go mod why -m 则回答主模块为什么需要它。最后用 go list -m -json all 看是否存在替换模块。三组输出要放在同一张证据表里：当前版本、上游要求、可用升级，分别对应“结果、原因、下一步”。

区分 replace、exclude 与工作区边界

如果 go list -m all 输出带有 =>，先检查主模块的 replace。它可以把某个版本替换成另一个模块或本地目录，替换后的模块还可能带来不同的依赖关系；此时你看到的版本号不一定对应下载内容。

exclude 只在主模块的 go.mod 中生效，被排除的版本会从模块图移除，MVS 再考虑更高的可用版本。若项目在 go.work 工作区内运行，还要确认命令实际使用的是哪个主模块集合：

go env GOWORK
go env GOMOD
go list -m all

GOWORK=off 可用于一次对照运行，让结果回到当前单模块；但它只是定位手段，不能替代团队对工作区依赖的正式决策。

让升级结果可复现并留在评审里

确认原因后再执行升级。只想提高一个直接依赖，可以使用：

go get example.com/codec@v1.8.0
go mod tidy
go list -m all

升级后重点看三件事：目标模块是否进入预期版本；间接依赖是否因新的模块图被一并提高；go.mod 与 go.sum 是否都纳入评审。不要把“远端已经有新版本”当成“本次构建会自动切换”的证据，MVS 的确定性正意味着新版本发布本身不会改变当前 build list。

最终可以把 go list -m all 保存为 CI 的诊断输出，必要时再用 go mod graph 追溯变化。这样下一次依赖冲突出现时，排查顺序就是：先看当前选择，再找上游要求，最后处理替换和工作区边界。

相关问题

为什么 go.mod 写了更高版本，go list -m all 还是旧版本？ 常见原因是当前命令运行在另一个模块或工作区，或者实际查看的模块路径带有主版本后缀。先核对 go env GOMOD 和完整模块路径。

go list -m -u all 显示了更新，为什么不会自动升级？ 该命令主要展示可用更新，不等于修改文件；需要用 go get 或编辑 go.mod 后再整理依赖。

replace 会不会只影响本地？ 写入主模块的 go.mod 后会影响使用该模块文件的构建；本地路径替换尤其需要在团队和 CI 中明确约定。