Go go list 提取构建依赖信息的用途

我在给构建脚本补“依赖清单”时，最初只执行 go list ./...，拿到一串包路径，却很快发现它不够用：脚本还需要知道包所在目录、所属模块，以及它继续依赖了哪些包。后来我把查询分成两种用途：人看或简单管道用 -f 模板，程序要保存多字段时用 -json。

go list 提取的不是一份脱离环境的静态清单。当前工作目录、模块模式、构建约束和命令参数都会影响包集合，所以“输出格式稳定”应该理解为字段和记录边界稳定，而不是任何环境下的依赖内容永远相同。

最实用的做法是先确定要列包还是展开依赖，再固定字段和运行上下文：文本管道用 -f，多字段消费用 -json，需要完整依赖闭包时明确加上 -deps。

官方地址：https://go.dev/cmd/go/

先把“列包”和“展开依赖”分开

不带额外参数时，go list 针对命令行给出的包模式列出匹配到的包。常见的 ./... 表示从当前位置展开当前模块内的包模式；它回答的是“哪些包被模式选中”，不是“这些包的全部传递依赖是什么”。

如果构建脚本要做依赖盘点，可以加 -deps。这个选项会把输入包的依赖也纳入列表，输出中可能出现标准库包和第三方包。不要把两种命令混在一起解释，否则同一项目的包数量变化很容易被误判成工具不稳定。

# 只看当前模块中匹配 ./... 的包路径
go list ./...

# 把每个目标包的依赖闭包也列出来，适合生成依赖清单
go list -deps ./...

这里的关键不是记住某个输出数量，而是明确输入模式。若只想观察模块自己的包，就不要在脚本里无条件把 -deps 加上；若要分析最终构建涉及的包，则要把它作为接口契约的一部分写进脚本说明。

用 -f 模板提取脚本真正需要的字段

默认输出适合人快速查看，但脚本通常不需要整条 Package 记录。-f 使用 Go 模板语法，可以只取 ImportPath、Dir 或 Module.Path 等字段。字段越少，后续处理越不容易被无关格式变化牵连。

# 只输出包导入路径，每行一个值，适合交给文本工具继续处理
go list -f '{{.ImportPath}}' ./...

# 同时输出包路径和源码目录，用制表符保留两列边界
go list -f '{{.ImportPath}}\t{{.Dir}}' ./...

# 输出包所属模块；没有模块信息时可能得到空值
go list -f '{{.ImportPath}}\t{{with .Module}}{{.Path}}@{{.Version}}{{end}}' ./...

模板里使用的是 go list 提供的 Package 字段，不是从默认文本里做正则截取。这样脚本的输入契约更清楚：字段名决定语义，分隔符决定列边界，空模块字段也可以由消费端明确处理。

如果要查看依赖集合，可以把 Deps 作为一个字段输出；不过它是集合，直接打印出来更适合人工排查，不一定适合长期存档。需要逐项处理时，通常应转向 JSON，或者在脚本里明确集合的排序和去重策略。

# 查看目标包的依赖集合；这是便于阅读的单条模板输出
go list -f '{{.ImportPath}}: {{.Deps}}' ./...

多字段场景用 -json 保留结构

-json 会把每个包的 Package 信息按 JSON 对象输出。它适合构建索引、生成依赖报告或交给另一个 Go 程序解码。与模板相比，它保留的字段更多，也能让调用方区分字符串、数组、布尔值和嵌套的模块对象。

# 输出包的结构化信息，便于后续按字段解析
go list -json ./...

# 输出目标包及其传递依赖的结构化记录
go list -deps -json ./...

消费 JSON 时不要假设整个命令只有一个对象。多个包会连续输出多个 JSON 对象，读取端应按 JSON 解码器逐个读取，直到遇到输入结束；不要把整段文本简单拼成一个数组，也不要用字符串查找字段。

package main

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

type Package struct {
    ImportPath string `json:"ImportPath"`
    Dir        string `json:"Dir"`
    Deps       []string `json:"Deps"`
}

func main() {
    // 让 go list 直接输出 JSON，避免先生成不可控的临时文本。
    cmd := exec.Command("go", "list", "-json", "./...")
    stdout, err := cmd.StdoutPipe()
    if err != nil {
        panic(err)
    }
    if err := cmd.Start(); err != nil {
        panic(err)
    }

    decoder := json.NewDecoder(stdout)
    for {
        var pkg Package
        // 一个命令可能连续产生多个对象，逐个解码直到 EOF。
        if err := decoder.Decode(&pkg); err != nil {
            if err == io.EOF {
                break
            }
            panic(err)
        }
        fmt.Printf("%s\t%s\t%d\n", pkg.ImportPath, pkg.Dir, len(pkg.Deps))
    }

    // 等待子进程结束，确保 go list 的失败状态不会被吞掉。
    if err := cmd.Wait(); err != nil {
        panic(err)
    }
}

这个例子只保留了消费端需要的三个字段。真实工具可以继续增加 Module、Imports 或错误字段，但应先确定接口版本，避免把一份面向人工阅读的完整 JSON 直接当作永久存储格式。

模块模式决定“同一命令”看到什么

Go 模块文档把主模块的 go.mod 和传递依赖的模块信息用于构建列表。包的 Module 信息、依赖版本和是否使用 vendor，都可能随运行上下文变化。因此在 CI、开发机和工作区之间比较 go list 结果时，先记录运行位置与模式。

# 显式要求只读模块文件，避免查询过程改写 go.mod 或 go.sum
go list -mod=readonly -json ./...

# 使用 vendor 目录时，把模式写进脚本而不是依赖机器默认行为
go list -mod=vendor -f '{{.ImportPath}}\t{{with .Module}}{{.Path}}@{{.Version}}{{end}}' ./...

如果项目根目录存在适用的 vendor 目录，构建命令可能自动使用它；显式指定 -mod 能让脚本意图更直接。工作区还可能通过 go.work 把多个模块组合在一起，此时同一个包模式在不同工作目录下并不一定对应同一组包。

我会怎样选择输出方式

我的经验是先按消费者分类，而不是先按命令参数分类。

如果报告要长期保存，我还会把运行目录、是否启用 vendor、输入模式和工具链版本一起记录。这样当 Deps 或 Module 字段变化时，排查对象是明确的，不会只剩下一份无法解释的差异文本。

相关问题

go list ./... 会列出所有传递依赖吗？不会。它首先列出模式匹配到的包；需要把依赖闭包加入结果时使用 -deps。

-f 和 -json 应该怎么选？只取少数稳定字段并继续走文本管道时用模板；需要嵌套字段、数组或多个消费者时用 JSON。

为什么同一项目在 CI 和本地的 Module 字段不同？优先检查工作目录、go.work、vendor 和 -mod 模式，再比较实际依赖版本。

能不能把 Deps 的打印结果直接当作稳定清单？不建议。先明确是否需要传递依赖、是否要去重排序，并固定运行上下文；模板文本更适合短期查看，JSON 更适合结构化消费。