Go list -m all 怎样定位实际使用的模块版本

项目出现“明明改过依赖，构建时却像用了另一个版本”的情况时，我通常先回到模块根目录执行 go list -m all。它列出的不是某个文件里写下的愿望版本，而是当前主模块与活动依赖经过模块版本选择后呈现的结果。想查 Go 模块系统的官方说明，可复制：https://go.dev/ref/mod。

先让 go list -m all 输出当前活动模块

命令要在目标模块的根目录执行，也就是能找到目标 go.mod 的目录。Go 官方文档把主模块定义为执行 go 命令所在目录所属的模块；因此如果人在仓库的子目录里，先回到模块根目录，结果才不会指向另一个工程。

# 在包含 go.mod 的模块根目录查看主模块和全部活动依赖
go list -m all

默认输出是一行一个模块。示意格式如下，实际模块名和版本会随项目不同：

example.com/order-service
github.com/example/config v1.4.2
golang.org/x/text v0.16.0
github.com/example/feature v0.3.0 => ../feature

all 表示所有活动模块：先列主模块，再列依赖；依赖按模块路径排序。图1把“命令入口—模块集合—输出字段”放在一张静态图里，便于把每一行当作一个模块记录来读。

从默认结果定位某个模块的实际版本

排查依赖时，先按完整模块路径找目标行，再看它后面的版本。不要只搜索包名：一个模块可以包含多个包，包导入路径的前缀才是模块路径。比如业务代码导入 golang.org/x/text/language，要在列表里定位的是 golang.org/x/text。

默认列表适合人工快速确认，但它把多个语义压缩成一行。如果看到 v0.3.0 => ../feature，左侧是原模块路径和版本，右侧是本地替换目标；真正参与当前本地构建的是右侧目录里的源码，而不是缓存里的左侧版本。

# 只筛选某个模块路径，保留完整模块行便于看替换关系
go list -m all | grep 'golang.org/x/text'

# 查询一个模块的结构化信息，适合脚本或排查本地替换
go list -m -json golang.org/x/text

这里的 grep 只是人工筛选输出，不改变 Go 的模块选择结果。若脚本要消费结果，不建议解析默认文本，而应读取 JSON 字段。

遇到 replace 时怎样确认真正参与构建的版本

go list -m -json all 会把每个模块展开成结构化对象。重点字段可以这样理解：Path 是模块路径，Version 是版本，Indirect 表示该模块只被间接需要，Replace 表示存在替换，Dir 是本地源码目录，GoMod 指向描述模块的 go.mod，Sum 是模块内容校验线索。

package main

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

type module struct {
    // Path 和 Version 用来输出模块记录的核心身份。
    Path string `json:"Path"`
    Version string `json:"Version"`
    // Replace 非空时，当前源码来源要继续查看替换对象。
    Replace *struct {
        Path string `json:"Path"`
        Version string `json:"Version"`
        Dir string `json:"Dir"`
    } `json:"Replace"`
    Dir string `json:"Dir"`
    Indirect bool `json:"Indirect"`
}

func main() {
    // -json 输出多个连续 JSON 对象，cmd 只负责取得模块查询结果。
    out, err := exec.Command("go", "list", "-m", "-json", "all").Output()
    if err != nil {
        // 命令失败时保留错误，不把空结果误当成没有依赖。
        panic(err)
    }
    dec := json.NewDecoder(bytes.NewReader(out))
    for dec.More() {
        var m module
        if err := dec.Decode(&m); err != nil {
            panic(err)
        }
        fmt.Printf("%s %s %s\\n", m.Path, m.Version, m.Dir)
    }
}

上面的示例展示字段关系，生产脚本还应先把连续 JSON 对象完整解码，并根据实际输出处理主模块空版本、错误字段和替换对象。文章重点不是写一个新的依赖工具，而是知道该看哪一层信息。

用 -f、-u 和 -versions 缩小查询范围

确认实际版本后，才有必要选择更窄的输出。-f 使用模块模板字段；它适合只输出路径、版本或本地目录。-u 会额外填充可用升级信息，但方括号里的版本只是可升级线索，不代表当前构建已经使用了它。

# 只输出模块路径和当前版本，便于复制到排查记录
go list -m -f '{{.Path}} {{.Version}}' all

# 在当前版本后显示可用升级信息
go list -m -u all

# 查看一个模块已知版本列表，按语义化版本排序
go list -m -versions golang.org/x/text

如果想让脚本稳定判断替换，可使用模板中的 {{.Replace}} 或直接使用 JSON；模板适合短输出，JSON 更适合需要判断空指针、目录和校验字段的程序。

几个容易误判的边界

• 把 go.mod 的 require 当成最终版本。模块图经过版本选择后，实际活动版本可能与某一条 require 的直觉不同，最终以 go list -m all 的当前结果为准。
• 把间接依赖当成无关依赖。Indirect 只描述它不是主模块直接声明的依赖，不等于它没有参与构建。
• 忽略 replace 右侧。本地替换时，右侧目录才是本机取源码的位置；先确认 Dir 和替换对象，再解释版本。
• 在错误目录执行。如果输出的主模块不是当前项目，先检查工作目录和 go env GOMOD，不要急着修改依赖文件。

常见问题

为什么 go list -m all 里有些模块没有版本号？

主模块本身通常不以已发布模块版本的方式显示；如果是本地替换，也要结合 Replace 和 Dir 看源码来源，不能只按版本列判断。

go list -m -u all 显示的新版本已经生效了吗？

没有。-u 只是把可用升级填入模块信息；它用于比较和决策，实际采用仍需要通过依赖修改命令改变模块图，再重新查询。

什么时候应该用 go list -m -json all？

当你需要判断替换、本地目录、间接依赖、模块文件或脚本化读取时使用 JSON；只想人工扫一眼当前版本时，默认文本更快。