Go list -json 怎么查看包的 GoFiles 和 EmbedFiles

在做 Go 工具链分析时，我经常需要回答两个很具体的问题：这个包实际纳入当前构建的 Go 源文件有哪些？//go:embed 模式最终匹配了哪些资源？直接看目录会把测试文件、被忽略文件和嵌入资源混在一起，比较稳妥的入口是 go list -json。

官方文档：https://pkg.go.dev/cmd/go#hdr-List_packages_or_modules

本文只讨论包 JSON 中的 GoFiles、EmbedPatterns 和 EmbedFiles。它们描述的是包元数据，不是构建缓存目录里的文件。

先把包级 JSON 输出出来

在一个模块目录中，可以先针对当前包查询：

# -json 输出包元数据；. 表示当前目录
go list -json .

如果要看模块下可匹配到的多个包，可以使用：

# ./... 只展开当前模块中的包模式
go list -json ./...

每个包对象可能同时包含 Dir、ImportPath、GoFiles、TestGoFiles、EmbedPatterns 和 EmbedFiles。字段采用省略空值的 JSON 表示，因此没有嵌入文件时，EmbedFiles 可能不会出现在对象中。

GoFiles 表示当前包参与构建的 Go 源文件

GoFiles 是包对象中的 Go 源文件名列表。它回答的是“在当前构建条件下，普通 Go 源文件有哪些”，不是目录里所有以 .go 结尾的文件。

测试文件有自己的字段：包内测试通常出现在 TestGoFiles，外部测试包出现在 XTestGoFiles。带有不匹配构建条件的文件，则可能落到 IgnoredGoFiles。因此，如果脚本只想统计参与普通包构建的源码，应优先读取 GoFiles，不要用文件系统 glob 代替它。

# 只从包 JSON 中取普通 Go 源文件数组
go list -json . | jq '.GoFiles // []'

这里的 // [] 是 jq 的缺省值写法：字段缺失时输出空数组，便于后续脚本统一处理。它不会把测试文件或嵌入资源补进来。

EmbedPatterns 和 EmbedFiles 不是同一个概念

使用 embed 包时，源码里会出现类似的声明：

package assets

import "embed"

//go:embed templates/*.html
var templates embed.FS

对这个包运行 go list -json 后，可以把两个层次分开看：

• EmbedPatterns：源码声明的匹配模式，例如 templates/*.html。
• EmbedFiles：这些模式实际匹配到的文件名清单，例如 templates/index.html。

所以，想知道“代码写了什么规则”，看 EmbedPatterns；想知道“当前包最终纳入了哪些嵌入文件”，看 EmbedFiles。一个模式可以匹配多个文件，多个模式匹配到的文件也可能合并到同一份清单中。

用模板直接提取字段

如果不想依赖 jq，可以让 go list 用模板输出字段。下面的模板把三类信息放在一起，字段缺失时由 Go 模板的零值表现为空：

# 用模板输出包路径和三个文件字段，便于脚本继续处理
go list -f '{{.ImportPath}}
GoFiles={{join .GoFiles ","}}
EmbedPatterns={{join .EmbedPatterns ","}}
EmbedFiles={{join .EmbedFiles ","}}' .

模板中的 join 来自 go list 的模板函数，适合把字符串切片压成一行。若文件名本身需要保留逐项边界，JSON 方式更可靠：

# 让 jq 保留数组结构，避免文件名分隔符造成歧义
go list -json . | jq '{import: .ImportPath, go: (.GoFiles // []), embed: (.EmbedFiles // [])}'

在自动化脚本中，建议把 ImportPath 一起保存。只输出文件名而不保存包身份，处理 ./... 的多包结果时容易把不同目录的同名文件混在一起。

三个容易混淆的边界

第一，GoFiles 不是全部 Go 文件。它不等于目录扫描结果；测试、构建条件和其他语言源文件都有独立字段。

第二，EmbedFiles 不是源码依赖列表。它只表示 //go:embed 模式匹配到的资源文件，不能用来替代 Imports 或 Deps。

第三，字段可能缺省。JSON 结构使用 omitempty 风格的公开字段，包没有嵌入声明时不要把缺省当成命令失败；解析端把缺省数组按空数组处理即可。

最后用一张表固定判断方式

实际使用时，可以记住一条简单关系：GoFiles 看“源码参与构建”，EmbedPatterns 看“声明了什么匹配规则”，EmbedFiles 看“规则落到了哪些资源”。当命令服务于多包脚本时，再把 ImportPath 一起带上，结果就不容易串包。

相关问题

为什么目录里有 .go 文件，但 GoFiles 没有它？通常需要继续看它是否属于测试文件、构建条件不匹配或被工具链归入其他字段。

没有 //go:embed 时 EmbedFiles 会怎样？字段可能缺省，解析时按空数组处理即可。

EmbedFiles 能代替依赖分析吗？不能。它描述嵌入资源；依赖分析应读取 Imports、ImportMap 或 Deps 等字段。