goList查询模块依赖图

项目依赖一多，直接打开 go.mod 往往只能看到声明，不能回答“最终选择了哪些版本”“哪个包把某个包带进来”。go list 和 go mod graph 要先分清观察对象：go list -m 面向模块，go list -deps 面向包，go mod graph 面向模块之间的要求边。

官方资料：https://go.dev/ref/mod

实际排查时，先用 go list -m -json all 看当前构建列表，再用 go list -deps -json ./... 下钻到包；如果要研究版本选择的边，再补 go mod graph。不要把三个命令的输出当成同一张图。

先确定你要看的依赖层级

规模较大的仓库通常同时存在三种“依赖图”。模块图回答“构建列表里有哪些模块、最终版本和替换目录是什么”；包图回答“某个入口包会加载哪些包”；要求图回答“某个模块版本要求哪个依赖版本”。前两者更适合定位代码来源，后一种更适合解释最小版本选择前的约束。

用 go list -m 看最终模块清单

-m 把 go list 的对象从包切换为模块，特殊模式 all 匹配当前构建列表。先用文本输出快速浏览，脚本或审计再用 JSON 保留替换信息和错误字段。

# 在包含 go.mod 的模块根目录执行，查看最终构建列表
go list -m all

# 输出机器可读的模块对象，便于后续逐条解析
go list -m -json all

# 只打印模块路径、版本和本地目录，替换模块时也保留路径信息
go list -m -f '{{.Path}} {{.Version}} {{.Dir}}' all

遇到 replace 时，JSON 中的 Replace 描述替换模块，Dir 可能指向替换后的本地目录。这样可以区分“声明过的模块路径”和“实际加载的代码位置”。如果要查看可升级版本，可加 -u，但它改变的是信息范围，不是依赖图本身。

用 go list -deps 下钻到包级传递依赖

模块清单仍然太粗时，使用 -deps。它会遍历命令行包及其依赖，并按依赖后序顺序列出包；命令行没有直接指定的包会带有 DepOnly 标记。./... 适合扫描当前模块的包集合，单个包路径则适合缩小问题范围。

# 追踪当前模块所有包的传递依赖，并保留结构化字段
go list -deps -json ./...

# 只关注某个命令包，减少大型仓库的输出量
go list -deps -json ./cmd/server

# 包存在构建错误时仍输出尽可能多的对象，错误由 Error 字段承载
go list -deps -e -json ./...

package main

import (
	"encoding/json"
	"fmt"
	"io"
	"os/exec"
)

type Package struct {
	ImportPath string   `json:"ImportPath"`
	Imports    []string `json:"Imports"`
	DepOnly    bool     `json:"DepOnly"`
	Error      *struct {
		Err string `json:"Err"`
	} `json:"Error"`
}

func main() {
	// 让 go list 负责加载包图，程序只解析它的 JSON 流。
	cmd := exec.Command("go", "list", "-deps", "-e", "-json", "./...")
	stdout, err := cmd.StdoutPipe()
	if err != nil {
		panic(err) // 管道创建失败时没有可解析的结果。
	}
	if err := cmd.Start(); err != nil {
		panic(err) // 启动 go 命令失败应直接暴露环境问题。
	}

	dec := json.NewDecoder(stdout)
	for {
		var pkg Package
		if err := dec.Decode(&pkg); err == io.EOF {
			break // JSON 对象读完，退出解析循环。
		} else if err != nil {
			panic(err) // 保留 JSON 结构错误，避免静默丢包。
		}
		if pkg.Error != nil {
			fmt.Printf("包 %s 加载失败：%s\n", pkg.ImportPath, pkg.Error.Err)
			continue
		}
		if !pkg.DepOnly {
			fmt.Println("入口包：", pkg.ImportPath) // DepOnly=false 表示命令行直接指定的包。
		}
	}
	if err := cmd.Wait(); err != nil {
		panic(err) // 子进程退出码仍需交给调用方处理。
	}
}

这个示例没有自己重建依赖闭包，而是把 Go 工具链的包加载结果作为输入。需要注意：Imports 是当前包直接导入的包，-deps 才负责把传递依赖也枚举出来；如果只想做模块归属分析，可在解析后按包路径与模块信息继续关联。

用 go mod graph 解释模块要求边

go mod graph 输出两列文本，每行是一条“模块版本要求依赖模块版本”的边。主模块没有 @version 后缀，其他顶点使用 path@version 标识。它适合回答“是谁要求了这个版本”，但不等同于最终包导入图。

# 输出模块要求边；每行是一个父模块和一个被要求的依赖模块
go mod graph

# 只保留包含某个模块关键字的边，便于缩小人工阅读范围
go mod graph | grep 'golang.org/x/'

# 按指定 Go 版本加载模块图，比较不同 go 语义下的结果
go mod graph -go=1.23

推荐把三种输出组合成一个排查闭环：先用 go list -m -json all 确认当前实际选中的模块和替换；再用 go list -deps -json 包路径 判断代码是否真的加载某个包；最后用 go mod graph 找出版本要求来自哪条边。这样既不会把“模块存在”误判成“包被使用”，也不会把包导入关系误读成版本选择规则。

大型仓库里最容易误读的三个点

• 没有 go.mod 就不能看 all。go list -m all 和 go mod graph 需要模块上下文，应从模块根目录或合适的工作区环境执行。
• 替换不是普通版本号。本地 replace 可能没有版本，分析脚本应优先处理 Replace 和 Dir。
• 包图不等于构建产物。构建标签、测试包和命令参数会改变加载范围，输出前应明确扫描的是 ./... 还是某个入口。

如果你的目标是做依赖报表，保存 JSON 而不是复制终端文本；如果目标是定位版本冲突，优先保留 go mod graph 的原始两列；如果目标是解释某个接口为何引入依赖，再回到包级 -deps 输出。

相关问题

go list -m all 和 go mod graph 有什么区别？

前者列出当前构建列表中的模块及其选中信息，后者列出模块要求边。一个偏“结果清单”，一个偏“约束关系”。

为什么 go list -deps 输出很多标准库包？

因为 -deps 会递归枚举入口包的全部包依赖，标准库包也属于依赖闭包的一部分；可以在脚本中按路径前缀过滤。