Go module graph pruning 如何减少构建依赖下载

项目依赖一多，最容易出现一种错觉：明明启用了 Go module graph pruning，执行命令时仍然看到模块被下载。先给结论：模块图裁剪减少的是 Go 在解析依赖要求时需要展开的传递图，不是保证每个未直接导入的模块都永远不进缓存。主模块的 go 指令、依赖自己的 Go 版本、测试与工具依赖，都会改变实际加载范围。

把“模块要求图”“包导入图”和本地 module cache 分开看，再用 go mod why -m 找路径，才能判断下载是否真的多余。

主模块的 go 版本决定图怎么装载

先看项目根目录的 go.mod。当主模块是 go 1.17 或更高时，Go 对声明了 go 1.17+ 的依赖只保留直接要求；它们更深层的传递要求可以从模块要求图中裁掉。与此同时，go.mod 会记录构建主模块包或测试所需的间接模块，这正是裁剪后仍能正确解析包的基础。

这不是一个独立的“开关”。可以先用下面的命令确认项目声明，并把修改限定在可复现分支：

# 查看主模块的 go 指令；它决定模块图采用哪套加载语义
grep '^go ' go.mod

# 只读方式构建，若 go.mod 需要被改动就直接报错
go build -mod=readonly ./...

如果主模块仍是 go 1.16 或更低，不能期待传递要求按新规则被裁掉；先评估最低支持版本，再考虑调整 go 指令。

先把要求边和选中版本分开

go mod graph 输出的是模块要求图：每行是一条“模块需要某个最低版本”的边。它适合回答“谁要求了这个模块”。而 go list -m all 展示的是当前构建列表，适合回答“最终选中了哪个版本”。在最小版本选择下，多个要求可能汇聚到更高版本，所以图里的边不能直接当成下载清单。

# 查看带 replacement 处理后的模块要求边
go mod graph

# 查看最终选中的模块版本；主模块位于输出第一行
go list -m all

# 只筛选目标模块，减少阅读噪声
go mod graph | grep 'example.com/codec'

# 判断某个模块中的包为何被主模块需要
go mod why -m example.com/codec

为什么还有依赖会被下载

最常见的原因不是裁剪失效，而是你执行的命令加载范围更大。一次 go build ./... 主要围绕当前构建包；go test ./... 还会引入测试包；go mod tidy 会扫描主模块的包、工具以及递归导入，并按构建标签考虑平台文件。于是 tidy 下载某个模块，并不等于线上二进制运行时会用到它。

还要检查四个边界：依赖模块自己的 go.mod 是否低于 1.17；是否有测试专用导入；是否声明了工具依赖；是否使用了 replace、私有模块或清空的本地缓存。被裁剪的要求仍可能在模块列表中出现，能否构建某个包则取决于它是否已被主模块显式纳入所需依赖范围。

用最小改动收敛依赖文件

先不要手删大量 // indirect。在干净分支运行 go mod tidy，观察变更，再用只读构建和测试复查；如果项目要兼容更老的 Go，可以通过 -compat 明确希望保留的兼容图，而不是凭感觉删除 go.sum。

# 让 tidy 按当前 go 指令整理依赖，并显示移除项
go mod tidy -v

# 需要兼容旧工具链时，显式指定兼容检查版本
go mod tidy -compat=1.17

# 复查所有包；readonly 防止构建偷偷改写 go.mod
go test -mod=readonly ./...

如果目标只是减少 CI 的网络等待，还应把模块缓存作为构建环境能力处理，例如在同一 Go 版本和相同代理策略下复用缓存。不要为了减少一次下载，移除测试或工具真正需要的间接要求；正确的收敛结果是依赖文件可解释、冷缓存构建能复现。

相关问题

模块图裁剪会删除 go.sum 中所有间接依赖吗？

不会。go.sum 还要服务兼容检查和实际加载的模块；是否保留由 Go 版本、tidy 与 -compat 共同决定。

为什么 go mod graph 里还有看似被裁剪的模块？

裁剪的是某些依赖的传递要求，模块本身仍可能有已知的选中版本，因此在模块列表或图的其他路径中出现并不矛盾。

go mod why -m 没有路径，是否可以立刻删模块？

不能立刻删。先检查测试、构建标签、工具文件和生成代码，再用干净缓存执行目标构建；确认没有所需包后，让 go mod tidy 做整理。

只升级主模块的 go 指令就能减少下载吗？

不一定。还要看依赖自身的 go 版本和命令加载范围；升级前应验证最低支持工具链、测试与 vendor 目录。

排查这类问题时，先判断“哪个命令在下载、为了哪个包下载、依赖边来自哪里”，再谈裁剪。三条命令配合起来，通常比反复手删 go.mod 更快找到真正的构建瓶颈。