Go go list -m -json 怎样导出模块构建信息

如果要把 Go 项目的依赖信息交给脚本、构建流水线或依赖报告工具，直接解析人类可读的 go list -m 输出很快会遇到麻烦：替换模块、主模块和版本查询的格式并不适合靠空格切分。更稳的做法是使用 go list -m -json，让 Go 按 Module 结构输出模块构建信息。

这篇只解决一个具体任务：怎样导出并理解 go list -m -json 的结果。开头先确定查询范围，然后说明 JSON 字段、替换关系和版本查询，最后给出脚本解析时最容易踩到的边界。

官方资料：https://go.dev/ref/mod#go-list-m

先决定要导出哪一类模块

go list 默认面向包；加上 -m 后，查询对象就变成模块。没有额外参数时，它描述当前主模块；使用 all 时，则面向当前构建列表中的模块；写出模块路径时，可以进一步指定一个模块或一个版本查询。

# 导出当前主模块的模块信息
go list -m -json

# 导出当前构建列表中的所有模块，每个模块一个 JSON 对象
go list -m -json all

# 查询指定模块当前选择的版本信息
go list -m -json golang.org/x/mod

这里的“构建信息”是模块加载和版本选择相关的信息，不是二进制文件里的编译信息，也不是运行中的服务状态。若命令在模块目录外执行，模块感知模式和参数要求可能不同；写进脚本前应固定工作目录或明确传入目标。

用 -json 导出可供程序读取的 Module 结构

Go 官方文档把模块查询结果描述为 Module 结构。常用字段包括 Path、Version、Time、Dir、GoMod、GoVersion、Main 和 Indirect。加上 -json 后，输出适合交给下游程序逐个解码。

# 将全部模块信息写入文件；输出是连续的 JSON 对象
go list -m -json all > modules.json

# 只选出路径与版本，适合快速查看文本结果
go list -m -f '{{.Path}} {{.Version}}' all

要注意，go list -m -json all 通常不是一个包住所有元素的 JSON 数组，而是多个连续的 JSON 对象。脚本应使用流式 JSON 解码器反复读取，不能简单地把整个文件交给只接受单个对象的解析函数。

Module 结构中的字段是否有值，还取决于查询对象和当前模块状态。例如主模块的 Main 为真，间接依赖可能带有 Indirect；如果模块加载失败，Error 可能包含错误信息。不要把空字段自动解释为模块不存在。

从字段判断模块来源和构建选择

导出结果时，可以把字段分成三组来理解。第一组是身份：Path 与 Version 说明模块是谁、当前选中了哪个版本。第二组是本地来源：Dir 指向本地模块文件目录，GoMod 指向描述模块的 go.mod 文件。第三组是构建语义：Main、Indirect 和 GoVersion 帮助脚本区分主模块、间接依赖和模块声明的 Go 版本。

package main

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

type module struct {
	Path      string `json:"Path"`
	Version   string `json:"Version"`
	Dir       string `json:"Dir"`
	GoMod     string `json:"GoMod"`
	GoVersion string `json:"GoVersion"`
	Main      bool   `json:"Main"`
	Indirect  bool   `json:"Indirect"`
}

func main() {
	// 让 go 命令输出全部模块的连续 JSON 对象。
	cmd := exec.Command("go", "list", "-m", "-json", "all")
	stdout, err := cmd.StdoutPipe()
	if err != nil {
		panic(err)
	}
	if err := cmd.Start(); err != nil {
		panic(err)
	}

	decoder := json.NewDecoder(stdout)
	for {
		var item module
		// Decode 每次读取一个对象，直到流结束，适配连续 JSON 输出。
		err := decoder.Decode(&item)
		if err == io.EOF {
			break
		}
		if err != nil {
			panic(err)
		}
		fmt.Printf("%s %s %s\\n", item.Path, item.Version, item.GoMod)
	}

	// 等待子进程结束，避免只读完标准输出却漏掉命令失败状态。
	if err := cmd.Wait(); err != nil {
		panic(err)
	}
}

这个示例只展示解析边界，不代表已在本机执行。真正接入流水线时，建议把子进程的标准错误单独记录，并根据退出状态决定是否生成依赖报告；不要只看到了几个 JSON 对象就认为命令成功。

replace、-u 和版本查询要单独看

如果 go.mod 中存在 replace，输出里的 Replace 字段会描述替换模块。此时不要只读取顶层 Path 和 Version 就当作最终源码来源：官方说明指出，替换模块存在时，Dir 会指向替换模块的目录，而不是被替换模块的源码目录。

# 查询当前构建列表，并保留替换关系字段
go list -m -json all

# 询问可用更新；Update 字段描述可升级到的模块信息
go list -m -u -json all

# 查询某个版本查询解析后的模块对象
go list -m -json golang.org/x/mod@latest

-u 会增加可用更新信息；对于撤回版本和弃用信息，也可能影响输出中的相关字段。它不是“把项目升级到最新版本”的命令，而是把更新候选展示出来。真正修改依赖仍应使用适合的模块操作命令，并把变更纳入代码评审。

指定 @latest、分支名或提交版本时，查询的是一个版本查询结果；它和当前主模块已经选中的版本不是同一个问题。若只是盘点当前构建列表，使用 all 更直接；若要了解一个模块可解析到哪个版本，再使用版本查询。

脚本解析时避开四个误区

此外，模块输出中的路径可能包含本机目录。生成共享报告时，先决定是否需要脱敏；不要把个人目录、令牌或构建机内部路径直接上传到公共日志。

常见问题

为什么 go list -m -json 没有列出所有依赖？

无参数时通常只描述主模块。要查看当前构建列表，显式使用 all；如果目标是某个特定模块，则直接写模块路径或版本查询。

为什么同一模块的 Dir 和 Path 看起来不对应？

最常见原因是存在 replace。Path 仍然表示模块身份，而 Dir 可能已经指向替换目标的本地目录，脚本应读取 Replace 了解这层关系。

可以用 go list -m -json 读取二进制的构建信息吗？

不应混用概念。它面向模块加载与版本选择；如果要查看已构建二进制携带的模块信息，应使用针对二进制的工具和对应数据来源。

总结

导出 Go 模块构建信息时，核心命令是 go list -m -json：用无参数查询主模块，用 all 查询构建列表，用模块路径或 @latest 查询指定对象。解析时按连续 JSON 对象读取，再结合 Path、Version、Dir、GoMod、Replace、Main 和 Indirect 判断模块身份与源码来源；遇到 -u 时，把它理解为查询更新信息，而不是自动升级。