Go module graph pruning 造成依赖缺失的修复

如果升级 Go 或执行 go mod tidy 后突然出现 no required module provides package，先别急着把 go 指令降回旧版本。常见原因是主模块进入了 Go 1.17 引入的 module graph pruning 语义：依赖图不再无条件加载所有传递依赖，某个原本“顺带可见”的模块没有被明确写进可用边界。

官方资料：https://go.dev/ref/mod

先判断：这是裁剪图变化还是普通依赖遗漏

Go 1.17 及更高版本的模块图，会裁掉某些 Go 1.17+ 依赖的传递 requirements；相应地，一个合规的 Go 1.17 go.mod 应该把构建所需的传递导入对应模块显式列出来。旧项目如果只保留了直接依赖，换工具链后就可能暴露缺口。

先保存完整错误，并检查三件事：主模块的 go 指令、实际运行的 go version，以及是否存在 vendor/。如果报错路径来自测试文件或特定 build tag，也要把同一构建条件带入排查；否则你看到的“缺失”可能只是当前命令没有加载那组包。

用两种视角找出被裁掉的模块

先看当前选中的模块版本：

# 查看当前构建使用的模块集合，先确认版本而不是猜测依赖来源
go list -m all

# 对比完整图与 Go 1.17 裁剪图，输出保存后便于搜索缺失模块
go mod graph -go=1.16 > graph-full.txt
go mod graph -go=1.17 > graph-pruned.txt

# 检查某个模块是否真的被主模块的包路径使用
go mod why -m example.com/codec

如果缺失模块只在完整图中出现，说明它依赖的声明位置或版本兼容性值得检查；如果两张图都没有它，优先确认导入路径对应的模块根路径是否写错。不要只看 go.sum：校验和存在不等于该模块已经成为当前构建的可选依赖。

修复方式：补足真正的模块边界

先让工具根据源码导入重新整理：

# 在主模块根目录执行，让 go.mod/go.sum 回到源码需要的状态
go mod tidy

# 若错误来自一个间接模块，明确加入提供该包的模块及已确认版本
go get example.com/codec@v0.8.2

# 再次整理，避免手工 require 留下无用条目
go mod tidy

示例中的模块名和版本要替换为错误导入路径对应的真实模块；版本应结合现有 go list -m all、项目兼容范围和发布记录选择，不能为了消错直接拉取最新版本。修复后，go.mod 里通常会出现一个带 // indirect 的 require。它不是“多余依赖”，而是在裁剪图里声明传递包来源的边界。

用兼容检查确认修复没有掩盖问题

如果项目要同时支持旧工具链，可在明确目标版本后整理：

# 例：将模块格式整理为 Go 1.17，并保留 Go 1.16 兼容检查
go mod tidy -go=1.17 -compat=1.16

# 若项目只支持新工具链，再按团队约定缩小兼容检查范围
go mod tidy -compat=1.17

# 以实际入口验证导入解析、测试和构建
go list ./...
go test ./...
go build ./...

如果 tidy 的兼容检查失败，不要用 -e 把失败吞掉就提交。先判断是旧工具链确实无法解析、依赖发布包的 go.mod 不完整，还是 build tag 与测试集合不同。只有在项目明确不再支持旧版本时，才使用合适的 -compat；这和降低主模块的 go 指令是两种不同的决策。

几个容易误判的边界

replace、工作区、测试依赖和 build tag 都会改变实际加载的包集合。若错误只在 go test 出现，应比较测试文件的导入；若只在 vendor 模式出现，应先判断 vendor 是否由当前 go.mod 重新生成。构建缓存只能影响产物复用，不能替代模块图声明，所以清理缓存通常不是 module graph pruning 缺依赖的根治方案。

相关问题

为什么 go.sum 里有记录，仍然提示缺少模块？

go.sum 只保存下载内容的校验和；它不负责把模块声明为当前模块图中的依赖。仍需检查 go.mod 和实际导入集合。

把缺失模块写成 indirect 就一定正确吗？

只有当它确实由主模块依赖链中的包间接使用时才合理。先确认模块提供的包和版本，再让 go mod tidy 整理，不要用注释掩盖未使用条目。

降低 go 指令能不能快速解决？

有时能暂时恢复旧的完整图，但会放弃裁剪语义，不能修复依赖发布不完整或导入路径错误。应把它当兼容性回退，而不是默认修复。