Go mod tidy 后为什么多出 indirect 依赖

很多项目第一次执行 go mod tidy，都会看到 go.mod 多出几行 // indirect。这通常不是 tidy 把依赖“乱加”了，而是 Go 在补齐可复现的模块图：某个直接依赖的内部包、测试包、构建标签分支，或一个不完整的上游 go.mod，需要这些模块才能被加载。indirect 只表示当前模块没有直接 import 它，不表示它没有用途。

官方文档：https://go.dev/ref/mod#go-mod-tidy

先区分间接依赖和无用依赖

require 块里的 // indirect 是依赖关系的标记。比如业务代码只 import 了 example.com/telemetry，而它内部又需要 example.com/codec，后者就可能被记录为间接依赖。Go 需要在模块文件中保留足够的信息，才能在另一台机器、另一个平台或测试命令中得到相同的模块选择结果。

require (
    example.com/telemetry v1.4.0
    // 当前模块没有直接 import，但 telemetry 的包图需要它
    example.com/codec v0.8.1 // indirect
)

因此，直接删掉这一行再运行构建，往往只会把问题推迟到下一个命令。真正要问的是：它由哪个包路径、测试或构建条件引入？如果没有任何路径能解释它，才进入清理判断。

用 go mod why 和 go mod graph 追出依赖路径

排查单个模块时，先看可读解释，再看完整图。下面的命令不会修改 go.mod，适合在提交前定位来源。

# 解释当前模块为什么需要目标模块
go mod why -m example.com/codec

# 查看模块版本之间的 require 边
go mod graph | grep 'example.com/codec'

# 看当前模块实际加载的包依赖（按需要替换包路径）
go list -deps ./... | grep 'example.com/codec'

go mod why -m 适合回答“从我的代码能否走到它”；go mod graph 展示的是模块级版本边，能发现是哪个直接模块声明了它。两者结果不同并不矛盾：前者更像使用路径，后者是完整模块选择图。

检查测试、构建标签和 go 指令版本

只在当前系统执行一次 go build，并不能代表 tidy 的扫描范围。模块文档说明，tidy 会考虑本模块测试，以及不同操作系统、架构和构建标签的包组合；而普通构建通常只加载当前请求涉及的那一部分。于是，一个只在 _test.go、//go:build linux 或工具包路径中出现的模块，也可能被写入 go.mod。

# 先把测试依赖也纳入排查，避免只看生产包
go list -deps -test ./... | grep 'example.com/codec'

# 查看 tidy 将要做什么，不直接改文件
go mod tidy -diff

还要留意 go.mod 中的 go 指令。Go 1.17 及之后的模块图会保留更多显式要求以支持延迟加载；用 -go=版本 整理时，保留的 require 集合也可能变化。这个变化不是“同一个 tidy 随机结果”，而是模块图兼容目标变了。

用 -diff 做一次可解释的清理

确认目标模块只是旧残留后，再让 tidy 正式更新文件。推荐把预览、测试和提交拆成三个动作：

# 第一步：只预览 go.mod 与 go.sum 的统一差异
go mod tidy -diff

# 第二步：确认当前模块和测试仍能构建
go test ./...

# 第三步：接受已经解释清楚的依赖变更
go mod tidy

如果 -diff 显示新增的 indirect 依赖，优先检查测试和平台分支；如果显示删除，先确认仓库里的生成代码、示例目录和工具依赖是否有对应的构建入口。最终提交时，go.mod 与 go.sum 应一起审阅，避免只提交其中一个文件。

常见问题

为什么我没有 import，go.mod 还要写它？

它可能是直接依赖的传递模块、测试依赖、平台分支依赖，或上游模块声明不完整。用 go mod why -m 和 go mod graph 先找路径。

indirect 依赖能不能手工删除？

不建议直接删除。先用 go mod tidy -diff 观察它是否会被重新加回，再结合 go test ./... 判断。

为什么不同 Go 版本 tidy 结果不一样？

go 指令版本会影响模块图加载与兼容目标，Go 1.17 之后的延迟加载规则也会保留更多显式要求。应在项目约定的 Go 版本下整理并提交。

参考资料：https://go.dev/doc/modules/managing-dependencies、https://go.dev/wiki/Modules、https://go.dev/doc/modules/gomod-ref