整理 go.mod 间接依赖并解释 tidy 的增删结果

整理 go.mod 的正确方式不是手工删除看起来“多余”的 // indirect，而是先让 go mod tidy -diff 给出源码与模块文件之间的差异，再解释每条变化来自哪个包、测试、工具或构建条件。只要依赖仍提供相关包，tidy 就可能保留它；只有依赖不再为扫描集合提供包时，require 才会被移除。

官方参考：https://go.dev/ref/mod

tidy 解决什么：让声明重新匹配源码

Go 官方参考对 go mod tidy 的定义很直接：补齐构建当前模块相关包所需的模块要求，移除不再提供相关包的模块要求，同时整理 go.sum。它不是“按字面删除未使用模块”的格式化器，而是根据加载到的包集合重新计算声明。

这里的包集合比一次当前平台上的 go build 更广。tidy 会加载主模块包、工具及递归导入，也考虑测试和除 ignore 外的构建标签。因此，某个依赖没出现在当前业务二进制中，仍可能因为 Windows 文件、集成测试或工具代码而合法存在。

先用 -diff 预览，不要直接改文件

-diff 会输出统一差异，并且在存在变化时返回非零状态，但不会修改 go.mod 或 go.sum。这很适合本地审查和 CI 检查。

# 只预览 tidy 需要进行的变化，不改写模块文件
go mod tidy -diff

# 确认差异合理后再正式整理
go mod tidy

# 最后查看版本控制中的实际改动
git diff -- go.mod go.sum

不要把 -diff 的非零退出码直接解释成命令失败。它可能只是告诉你模块文件尚未整洁。真正需要处理的加载错误，会在差异之外显示包解析、版本或网络问题。

五类增删结果怎么解释

// indirect 不是“可删标记”。官方参考把它定义为：该模块没有提供被主模块包直接导入的包。Go 1.17 及以上为了模块图裁剪和懒加载，会在 go.mod 中记录更完整的间接要求，所以升级 go 指令后 indirect 行变多并不反常。

用三个命令找到变化来源

包图回答“哪个导入路径需要它”，模块图回答“哪个模块版本要求它”。两者不要混为一谈。

# 查主模块到目标模块中任意包的最短包导入路径
go mod why -m example.com/dependency

# 查模块要求边，定位谁抬高或带入了目标版本
go mod graph | grep 'example.com/dependency'

# 查看最终构建列表中的选中版本
go list -m all | grep 'example.com/dependency'

go mod why -m 即使带 -m，查询的仍是包图；go mod graph 输出的是模块要求图。前者适合解释“为什么需要”，后者适合解释“为什么选中这个版本”。如果 why 没显示当前平台的路径，还要继续检查测试、工具文件和构建标签。

Go 版本为什么会改变 indirect 行

主模块的 go 指令会影响模块图裁剪、懒加载和间接要求的记录方式。给 tidy 传 -go 会更新 go 指令，并按目标版本增删间接要求；-compat 则控制兼容性检查所依据的 Go 版本。

# 按目标 Go 版本预览变化，同时检查指定兼容版本
go mod tidy -diff -go=1.23 -compat=1.22

这不是日常清理时随手使用的“瘦身参数”。只有项目确实准备调整最低 Go 版本时才传 -go，并把 go 指令、工具链、CI 和依赖要求一起审查。否则应让 tidy 沿用当前 go.mod 的版本语义。

一个可复现的整理示例

假设项目删除了旧日志适配器，却仍看到日志模块。先运行 tidy -diff；如果 require 没被删除，用 why 查入口。结果可能指向测试辅助包，说明依赖仍然有效。若清理测试 import 后再次预览，require 与相关 go.sum 项一起消失，这才是由源码事实驱动的删除。

# 搜索所有 Go 文件中的真实导入，包含测试和工具代码
rg 'example.com/legacylog' --glob '*.go'

# 清理源码入口后重新预览模块文件差异
go mod tidy -diff

# 差异确认无误后写入并运行项目测试
go mod tidy
go test ./...

如果项目维护 vendor 目录，模块文件整理后还应重新运行 go mod vendor，让 vendor/modules.txt 与新声明一致。不要直接在 vendor 内修改依赖源码，因为下一次重建会覆盖这些变化。

常见误区

indirect 行越少，构建就越快吗？

没有这种直接关系。indirect 是模块关系记录，不是运行时加载清单。手工删行反而可能让后续命令重新补回，制造无意义差异。

能否只提交 go.mod，不提交 go.sum？

不建议拆开由同一次 tidy 产生的相关变化。go.sum 保存所需模块内容的校验信息，二者应作为同一可复现变更审查。

为什么本机 tidy 无变化，CI 却报差异？

先比较 Go 版本、go 指令、工作区设置和源码是否完整。不同工具链语义或缺失的生成文件、私有模块访问条件，都可能让加载集合不同。

tidy 能替代 go get 升降级依赖吗？

不能。tidy 负责使声明匹配源码；显式升降级应使用 go get module@version 或 @none，再用 tidy 收尾。