依赖图剪枝发生在模块加载阶段，早于包解析和编译，是go build等命令在加载模块图时执行的前置逻辑，基于AST导入路径动态裁剪未被引用的module及其传递依赖。
依赖图剪枝发生在哪个构建阶段
依赖图剪枝（module graph pruning）不是编译器行为，而是 go build 和 go list 等命令在模块加载阶段执行的前置逻辑，发生在「模块图加载」环节，早于包解析和编译。它不改变源码或 go.mod 内容，只影响本次构建实际参与的模块集合。
关键点在于：剪枝只对当前构建目标的 import 路径生效，不修改 go.mod 中的 require 列表，也不影响 go mod tidy 的结果。它属于运行时裁剪，不是静态配置。
- 触发条件是 Go 1.17+ 且构建时未显式禁用（如未设
GODEBUG=godebug=off） - 剪枝依据是 AST 级导入路径，而非
go.mod中声明的 module - 若某 module 的某个 package 完全未被任何已启用的 import 链路引用，该 module 及其传递依赖会被跳过加载
为什么 go mod graph 仍显示被剪掉的依赖
go mod graph 输出的是完整模块图——即 go.mod 文件中所有 require 及其传递依赖构成的静态图，它不模拟实际构建路径，也不执行剪枝逻辑。所以即使某 module 在构建中被剪掉，只要它出现在 go.mod 的依赖闭包里，go mod graph 就会把它列出来。
真正反映剪枝效果的是 go list -m all 的输出：它只列出本次构建实际加载的 module，被剪掉的 module 不会出现其中。你可以对比两者差异来验证剪枝是否生效：
立即学习“go语言免费学习笔记（深入）”；
初始化并管理阿里云SDK Go 客户端，涵盖 sync.Once 单例、goroutine 安全、endpoint 与 region 配置、VPC 端点及调试。
go mod graph | grep example.com/c go list -m all | grep example.com/c
前者有、后者无，就说明 example.com/c 被成功剪枝。
剪枝失效的常见原因
剪枝不是万能的，以下情况会导致本该被剪掉的 module 依然被加载：
- 代码中存在动态 import（如通过
plugin.Open或反射加载包名字符串），AST 无法静态分析，剪枝器视为“可能使用”，保留整个 module -
go.mod中对该 module 有直接require（哪怕代码里没用），它就不会被剪 - 使用了
//go:embed或//go:generate引用了该 module 下的文件，Go 工具链会保守保留 - 启用了
-mod=vendor模式，模块加载绕过 graph 剪枝逻辑，直接读 vendor 目录
尤其注意：replace 和 exclude 指令本身不影响剪枝判断，但它们可能间接导致 module 被保留（比如 replace 后的本地路径被 import 引用）。
如何验证剪枝是否起效
最直接的方式是观察模块加载耗时和网络请求变化，而不是只看输出列表：
- 加
-x参数运行go build -x，搜索go mod download行——被剪掉的 module 不会出现下载日志 - 设置
GODEBUG=modload=1，会打印每一步模块加载决策，含pruned标记的行即为被剪模块 - 对比 Go 1.16 和 Go 1.17+ 下同一命令的执行时间，大型项目中第三方未使用 module 较多时，剪枝可减少数百毫秒模块解析开销
剪枝真正的价值不在“少下几个包”，而在于避免因无关 module 缺失或校验失败（如 missing go.sum entry）导致构建中断——这是开发者最容易忽略却最常踩的坑。
