Go modules 怎样用 go mod graph 查依赖关系

如果你想知道一个 Go 模块“声明了哪些依赖、依赖之间又要求了什么版本”，最直接的命令是 go mod graph。它打印的是模块需求图：每行两个字段，左边是一个模块版本，右边是它要求的依赖；主模块没有 @version 后缀。

官方地址：https://go.dev/ref/mod

先在目标模块根目录执行 go mod graph，再根据主模块名或依赖名筛选。需要确认最终被选中的版本时，用 go list -m all；需要解释“为什么需要它”时，用 go mod why -m。

先看懂 go mod graph 输出的两列

Go 官方文档把输出定义为模块需求图的边。节点是具体的模块版本，边表示一个模块对另一个模块提出最低版本要求。主模块自身没有版本，因此常见的第一列会是你的 module 声明值。

module example.com/report

# 在模块根目录打印模块需求边
go mod graph

# 示意输出：每行依次是“提出要求的模块”和“被要求的模块版本”
example.com/report golang.org/x/text@v0.16.0
example.com/report golang.org/x/net@v0.28.0
golang.org/x/net@v0.28.0 golang.org/x/text@v0.13.0

上面的第三行关系表示 golang.org/x/net@v0.28.0 至少要求某个版本的 golang.org/x/text。它不是说程序一定直接导入了 x/text，也不是最终选择结果；最终版本还要经过模块版本选择。

输出很长时，可以先看主模块的直接需求：

# 把左侧节点限定为当前模块，路径按项目实际 module 值替换
go mod graph | awk '$1 == "example.com/report" { print }'

# 统一排序，便于保存两次结果后做文本比较
go mod graph | sort

把完整图缩小成可判断的局部

排查依赖时，不建议只盯着一屏输出。可以先保存图，再围绕一个模块名反查它出现在哪些边上：

# 只保留包含目标模块名的边，便于观察它的上游和下游关系
go mod graph | grep 'golang.org/x/text'

# 查看主模块当前构建列表中的最终模块版本
go list -m all

go list -m all回答的是“构建列表里最终使用哪些模块版本”，而 go mod graph回答的是“各模块提出了哪些最低版本要求”。两者不一致并不代表命令出错：多个依赖可能要求同一模块的不同版本，版本选择后只会保留被选中的版本。

如果你的问题是“这个模块为什么会被带进来”，改用：

# -m 表示按模块询问，而不是按包询问
go mod why -m golang.org/x/text

它给出从主模块到目标模块中某个包的最短导入路径。也就是说，go mod why偏向解释导入原因，go mod graph偏向展示模块声明关系，不能相互替代。

遇到版本差异时看 -go 和 replace

模块图会受加载规则影响。Go 官方文档提供了 -go=version 参数，它让命令按指定 Go 版本加载模块图，而不是直接采用 go.mod 中的 go 指令。比较旧环境和当前环境时，可以分别保存两份输出：

# 按项目 go.mod 的规则查看当前模块图
go mod graph

# 用指定 Go 版本的模块图加载规则做对照
go mod graph -go=1.21

如果 go.mod 中存在 replace，官方定义是输出会应用替换关系。因此看到本地路径或替代模块时，先回到 go.mod 对照 replace，不要把它误判为代理下载到的原始版本。

最后用下面这张速查表选择命令：

常见问题

go mod graph 能直接看出代码导入关系吗？不能。它展示的是模块需求图；要解释包从哪里被导入，使用 go mod why 更合适。

为什么 graph 里出现的版本和 go list 不一样？前者记录依赖提出的最低版本要求，后者反映模块版本选择后的构建列表，多个要求经过选择后可以收敛到一个版本。