Go fs.Glob 怎样按模式查找嵌入文件

在 Go 项目里把模板、配置片段或前端静态资源编译进程序后，常见需求不是读取某一个固定文件，而是按目录和扩展名找到一组文件。这个场景可以组合 embed.FS 与 fs.Glob：前者提供只读的嵌入文件系统，后者按 path.Match 规则返回匹配的嵌入路径。

最小写法是先声明 embed.FS，再把类似 assets/templates/*.tmpl 的模式传给 fs.Glob。没有匹配项时不要把它当成异常；只有模式本身格式错误时，才需要按错误分支处理。

本文目标：用一个包含 JSON 配置和模板文件的嵌入目录，说明路径根、通配符、返回值和后续读取之间的关系。

先明确嵌入目录和 Glob 的匹配根

//go:embed 的模式相对于声明变量所在的包目录。下面的示例把整个 assets 目录嵌入到只读的 embed.FS 中，程序看到的路径仍然包含 assets/ 这一层：

package main

import (
	"embed"
	"fmt"
)

// assets 保存与当前 Go 包相对的静态目录，编译时写入程序。
//go:embed assets
var assets embed.FS

func main() {
	// 这里用 / 表示嵌入文件系统的路径分隔符。
	entries, err := assets.ReadDir("assets")
	if err != nil {
		// 目录名写错或嵌入声明没有覆盖它时，先保留原始错误。
		panic(err)
	}
	fmt.Println(len(entries))
}

假设包目录下的文件布局如下：

assets/
├── config/app.json
└── templates/
    ├── admin.tmpl
    └── home.tmpl

此时 fs.Glob(assets, "assets/templates/*.tmpl") 才能命中两个模板。如果把模式写成 templates/*.tmpl，它会从嵌入文件系统的根开始匹配，自然找不到带有 assets/ 前缀的路径。

用层级模式找到嵌入文件

fs.Glob 的函数签名是 fs.Glob(fsys fs.FS, pattern string) ([]string, error)。模式沿用 path.Match，可以描述层级名称；其中 * 匹配当前路径段里的任意字符，但不会跨过 /。

下面分别查找配置文件和模板文件，并把匹配路径交给后续读取逻辑：

package main

import (
	"embed"
	"fmt"
	"io/fs"
	"log"
)

//go:embed assets
var assets embed.FS

func main() {
	patterns := []string{
		"assets/config/*.json",    // 只查找 config 这一层的 JSON 文件。
		"assets/templates/*.tmpl", // 只查找 templates 这一层的模板文件。
	}

	for _, pattern := range patterns {
		matches, err := fs.Glob(assets, pattern)
		if err != nil {
			// 模式语法错误时，继续处理没有意义，直接记录并退出。
			log.Fatalf("匹配模式 %q 失败: %v", pattern, err)
		}
		fmt.Printf("%s -> %v\n", pattern, matches)
	}
}

需要注意，assets/*/*.tmpl 可以匹配 assets/templates/home.tmpl 这类两段路径，但不会把任意深度目录都当成递归通配。嵌入模式本身也必须使用相对包目录的合法路径，不能用文件系统绝对路径或带 .. 的路径。

无匹配和错误模式要分开处理

fs.Glob 返回的两个结果需要分别理解：

• 模式合法但没有文件命中时，matches 为空，err 为 nil。
• 模式语法不合法时，返回 path.ErrBadPattern，调用方应该先处理 err。
• 默认实现遍历目录时，会忽略读取目录过程中的 I/O 错误；不能把空结果理解成“整个嵌入目录已经被完整验证”。

因此，业务代码可以把“找不到可选资源”和“模式写错”分成两个分支：

func findTemplates(fsys fs.FS, pattern string) ([]string, error) {
	// 先让 fs.Glob 判断模式是否合法，再解释空结果。
	matches, err := fs.Glob(fsys, pattern)
	if err != nil {
		return nil, fmt.Errorf("模板模式无效 %q: %w", pattern, err)
	}
	if len(matches) == 0 {
		// 合法模式没有命中，交给上层决定是否使用默认模板。
		return []string{}, nil
	}
	return matches, nil
}

上面的函数使用了 fmt 和 io/fs，完整导入时不要遗漏。若模板是必选资源，可以在 len(matches) == 0 时返回业务错误；若是可选资源，则继续走默认配置。

匹配后直接用 fs.ReadFile 读取内容

fs.Glob 只负责返回路径名，不会把文件内容一起返回。嵌入文件的路径要原样交给 fs.ReadFile，不要把它转换成操作系统本地绝对路径：

func readJSONFiles(fsys fs.FS, pattern string) (map[string][]byte, error) {
	// 先找出所有匹配路径，再按同一组路径读取内容。
	matches, err := fs.Glob(fsys, pattern)
	if err != nil {
		return nil, fmt.Errorf("查找嵌入文件失败: %w", err)
	}

	result := make(map[string][]byte, len(matches))
	for _, name := range matches {
		data, err := fs.ReadFile(fsys, name)
		if err != nil {
			// 保留具体文件名，便于定位声明或目录结构问题。
			return nil, fmt.Errorf("读取嵌入文件 %q 失败: %w", name, err)
		}
		result[name] = data
	}
	return result, nil
}

这里的路径键仍然是 assets/config/app.json 这样的 slash-separated 名称。对于需要按文件名建立路由、模板注册表或配置索引的程序，可以把它作为稳定键；如果只关心文件内容，则可在读取后自行提取末级名称。

用 fs.Sub 把匹配根移到嵌入目录内部

如果后续代码只操作 assets 目录，可以先创建一个子文件系统，再使用更短的模式。fs.Sub 不会复制文件，它只是把一个目录映射成新的 fs.FS 视图：

func findFromAssets(fsys fs.FS) ([]string, error) {
	// 把 assets 作为新的根，后面的模式不再重复 assets/ 前缀。
	assetFS, err := fs.Sub(fsys, "assets")
	if err != nil {
		return nil, fmt.Errorf("创建 assets 子文件系统失败: %w", err)
	}

	// 模式相对于 assetFS 根目录，仍然使用正斜杠。
	matches, err := fs.Glob(assetFS, "templates/*.tmpl")
	if err != nil {
		return nil, fmt.Errorf("查找模板失败: %w", err)
	}
	return matches, nil
}

采用这个写法后，返回值会是 templates/home.tmpl，而不是 assets/templates/home.tmpl。因此要提前确定路径键的范围，避免同一个程序里混用两种根目录导致注册表重复或读取失败。

一张表记住 fs.Glob 的使用边界

常见问题

为什么模式写成 assets/**/*.tmpl 找不到所有深层模板？

fs.Glob 使用的是 path.Match 语法，** 不是额外的“任意深度目录”语义。应按实际目录层级设计模式，或者重新组织嵌入资源的根和读取逻辑。

没有匹配文件时为什么没有 error？

合法模式没有命中属于正常结果，返回空切片和空错误。是否报业务错，要由调用方根据资源是否必选来决定。

fs.Glob 会返回磁盘上的绝对路径吗？

不会。它返回的是传入 fs.FS 视图中的文件名；对 embed.FS 来说就是相对于嵌入根的 slash-separated 路径。

总结

用 embed.FS 保存资源后，fs.Glob 的关键是三件事：模式根必须和嵌入路径一致，通配符不能被误解为递归匹配，空结果要与错误模式分开处理。得到匹配路径后，再把原路径交给 fs.ReadFile；如果整个模块都围绕某个资源目录工作，则用 fs.Sub 固定一个更清晰的根。