go list command

文章目录

1.简介
2.基本语法
- [2.1 格式](#2.1 格式)
- [2.2 常用包路径写法](#2.2 常用包路径写法)
- [2.3 默认输出](#2.3 默认输出)
- [2.4 结构化输出](#2.4 结构化输出)
- [2.5 模块模式格式](#2.5 模块模式格式)
[3. 选项](#3. 选项)
- [3.1 输出控制](#3.1 输出控制)
- [3.2 范围控制](#3.2 范围控制)
- [3.3 模块模式](#3.3 模块模式)
- [3.4 常用模板字段](#3.4 常用模板字段)
[4. 示例](#4. 示例)
[5. 常见问题](#5. 常见问题)
- [5.1 `./...` 与 `...` 有什么区别？](#5.1 ./... 与 ... 有什么区别？)
- [5.2 模板中的 `{{}}` 需要转义吗？](#5.2 模板中的 {{}} 需要转义吗？)
- [5.3 `-e` 会掩盖真正的错误吗？](#5.3 -e 会掩盖真正的错误吗？)
- [5.4 如何只查看某个包的直接依赖？](#5.4 如何只查看某个包的直接依赖？)
[6. 小结](#6. 小结)
参考文献

1.简介

go list 的核心作用是以可编程的方式输出 Go 包和模块的信息。

它的典型用途包括：

确认某个包是否存在
列出项目的所有依赖
查看依赖是否有可用更新
导出包或模块的元数据供脚本处理

与 go build、go run 不同，go list 不编译代码，只做解析和查询，因此速度极快，非常适合嵌入脚本或 CI 流程。

go list 有两种工作模式：

模式	触发方式	操作对象
包模式	默认	包（package）
模块模式	加 `-m`	模块（module）

2.基本语法

2.1 格式

bash 复制代码

go list [-f format] [-json] [-m] [list flags] [build flags] [packages]

不带参数时，go list 列出当前目录的包信息。

2.2 常用包路径写法

写法	含义
`go list`	当前目录的包
`go list ./...`	当前项目及所有子目录的包
`go list ...`	工作区所有包
`go list hash`	标准库 `hash` 包
`go list github.com/gin-gonic/gin`	外部包

2.3 默认输出

最简单的输出是导入路径：

bash 复制代码

$ go list github.com/gin-gonic/gin
github.com/gin-gonic/gin

2.4 结构化输出

go list 的真正价值在于结构化输出，有两种方式：

JSON 格式：

bash 复制代码

go list -json hash

输出包的所有元数据，包括 Dir、ImportPath、Name、GoFiles、Imports、Deps、Doc 等字段。

Go 模板格式：

bash 复制代码

go list -f '{{.ImportPath}}: {{.Dir}}' hash

输出：

复制代码

hash: /usr/local/go/src/hash

2.5 模块模式格式

加 -m 后，操作对象变为模块：

bash 复制代码

go list -m all          # 列出所有模块
go list -m -json gin    # 以 JSON 输出某模块信息

3. 选项

3.1 输出控制

选项	作用
`-json`	以 JSON 格式输出
`-f`	用 Go 模板自定义输出格式

3.2 范围控制

选项	作用
`-deps`	同时列出所有依赖
`-test`	包含测试相关文件信息
`-e`	遇到错误也继续处理，不中断

3.3 模块模式

选项	作用
`-m`	切换到模块模式
`-u`	配合 `-m`，检查可用更新
`-versions`	配合 `-m`，列出所有可用版本

3.4 常用模板字段

字段	含义
{``{.ImportPath}}	导入路径
{``{.Name}}	包名
{``{.Dir}}	包所在目录
{``{.GoFiles}}	Go 源文件列表
{``{.Imports}}	直接依赖
{``{.Deps}}	所有依赖（含间接）

各选项的具体用法与组合方式，见第 4 章示例。

| {``{.Doc}} | 包文档摘要 |
join 是 Go 模板内置函数，用于把切片拼成字符串，例如 {``{join .Deps "\n"}}。

4. 示例

（1）确认包是否存在。

bash 复制代码

go list github.com/go-sql-driver/mysql

存在则输出导入路径，不存在则报错。

在脚本中判断：

bash 复制代码

if go list github.com/foo/bar > /dev/null 2>&1; then
    echo "包存在"
else
    echo "包不存在"
fi

（2）查看模块的可用版本列表。

shell 复制代码

go list -m -versions <mod-path>

比如查看 gin 框架的可用版本。

shell 复制代码

go list -m -versions github.com/gin-gonic/gin
github.com/gin-gonic/gin v1.1.1 v1.1.2 v1.1.3 v1.1.4 v1.3.0 v1.4.0 v1.5.0 v1.6.0 v1.6.1 v1.6.2 v1.6.3 v1.7.0 v1.7.1 v1.7.2 v1.7.3 v1.7.4 v1.7.5 v1.7.6 v1.7.7 v1.8.0 v1.8.1 v1.8.2 v1.9.0 v1.9.1 v1.10.0 v1.10.1 v1.11.0 v1.12.0

（3）列出项目的所有直接依赖。

bash 复制代码

go list -f '{{join .Imports "\n"}}' ./... | sort -u

（4）列出某个包的所有依赖。

bash 复制代码

go list -f '{{join .Deps "\n"}}' hash

（5）导出依赖树为 JSON。

bash 复制代码

go list -json -deps ./... > deps.json

后续可用 jq 等工具分析。

（6）列出所有模块

bash 复制代码

go list -m all

列出所有模块指的是列出当前项目的主模块，以及它依赖的所有模块（包括直接依赖和间接依赖）。

这里的 -m 是关键：它把 go list 的操作对象从"包（package）"切换成"模块（module）"。all 则是一个特殊模式，表示"主模块 + 全部依赖模块"。

（7）检查依赖更新

bash 复制代码

go list -m -u all

输出中会标注可用更新：

复制代码

github.com/gin-gonic/gin v1.10.0 [v1.10.1]

（8）格式化输出依赖更新。

bash 复制代码

go list -m -u -f '{{.Path}} {{.Version}} -> {{.Update.Version}}' all

输出：

复制代码

github.com/gin-gonic/gin v1.10.0 -> v1.10.1

（9）查看某模块的详细信息

bash 复制代码

go list -m -json github.com/gin-gonic/gin

输出模块的 Path、Version、Time、Dir、GoMod 等字段。

（10）找出依赖了某个包的所有包

bash 复制代码

go list -f '{{.ImportPath}} {{join .Deps " "}}' ./... | grep "golang.org/x/sync"

（11）宽容模式处理错误

bash 复制代码

go list -e -json ./...

5. 常见问题

5.1 `./...` 与 `...` 有什么区别？

./... 匹配当前目录及其子目录下的包；
... 匹配当前工作区（workspace）内的所有包，范围更大。

在单模块项目中两者通常等价，但在多模块工作区中差异明显，建议按需选择。

5.2 模板中的 {``{}} 需要转义吗？

在 shell 中直接使用 -f '{``{.ImportPath}}' 时，单引号可避免 shell 展开。若在脚本中拼接模板，注意 $ 等字符的转义。

5.3 `-e` 会掩盖真正的错误吗？

-e 让 go list 遇到无法解析的包时继续输出，适合排查不稳定项目。但正常开发中建议先去掉 -e，让错误直接暴露，便于定位问题。

5.4 如何只查看某个包的直接依赖？

用 {``{.Imports}}（直接依赖）而非 {``{.Deps}}（含间接依赖），例如：

bash 复制代码

go list -f '{{join .Imports "\n"}}' hash

6. 小结

go list 的核心价值是把 Go 的包和模块信息变成可编程的数据：

包模式 ：go list <pkg> 查询包信息，配合 -json 或 -f 输出结构化数据
模块模式 ：go list -m 切换视角，管理依赖、检查更新
脚本友好 ：配合 grep、jq、sort 做自动化分析
不编译代码：只解析元数据，速度快，适合 CI 和脚本

掌握 go list，你就能用命令行快速回答"这个包在哪""依赖了什么""有没有更新"等问题，无需打开 IDE 或手动翻 go.mod。

文章目录

1.简介

2.基本语法

2.1 格式

2.2 常用包路径写法

2.3 默认输出

2.4 结构化输出

2.5 模块模式格式

3. 选项

3.1 输出控制

3.2 范围控制

3.3 模块模式

3.4 常用模板字段

4. 示例

5. 常见问题

5.1 ./... 与 ... 有什么区别？

5.2 模板中的 {``{}} 需要转义吗？

5.3 -e 会掩盖真正的错误吗？

5.4 如何只查看某个包的直接依赖？

6. 小结

参考文献

5.1 `./...` 与 `...` 有什么区别？

5.3 `-e` 会掩盖真正的错误吗？