Go embed.FS设计 glob 目录避免空匹配的配置方法

Go 项目把模板、静态资源放进 embed.FS 后，glob 目录最容易混淆的是“没有匹配”发生在哪一层：//go:embed 属于构建期，模式必须匹配至少一个文件或非空目录；fs.Glob 属于运行期，找不到文件通常只是返回空结果。设计时给目录保留稳定入口，再对运行时零匹配单独做业务判断，就能避免构建失败和误报警。

先分清构建期模式和运行期模式

//go:embed 使用的是相对当前 Go 源文件所在包目录的路径模式。每个模式至少要命中一个文件或非空目录，否则构建阶段就会失败；匹配结果还不能越过模块边界、符号链接或另一个 go.mod 所在的子模块。这里的“空匹配”不是程序运行后的业务状态，而是资源清单没有满足编译器要求。

目录模式和通配符模式也不是一回事。嵌入 assets 会递归获取目录树，但目录遍历默认排除名字以 . 或 _ 开头的文件；assets/* 则可能匹配目录下的点文件。要让规则稳定，建议把真正需要发布的入口文件写成普通名称，并把环境专属文件放在不会被模式意外收集的位置。

package web

import "embed"

// content 保存模板和静态资源，两个模式都相对当前包目录解析。
//go:embed templates/*.tmpl static
var content embed.FS

// 如果 static 目录可能被裁剪，里面应保留明确的非隐藏入口文件，
// 例如 static/index.html 或 static/manifest.json，避免构建期目录为空。

用稳定入口避免 embed 目录变成空匹配

实际项目常在打包脚本中按环境删除资源，或者在新仓库初始阶段只创建目录没有文件。这时不要指望空目录满足 //go:embed static；更稳的做法是让目录拥有一个有业务意义的普通文件，例如前端资源的 index.html、版本清单或默认模板。若确实需要收集点文件，可以改用 all:static，但这会扩大嵌入范围，应该把它视为明确的资源契约。

路径模式统一使用正斜杠，即使构建机是 Windows；模式不能含有 .、..、空路径段，也不能以斜杠开头或结尾。把这些约束提前写进资源目录约定，比在发布前才追查一条难读的构建错误更省时间。

在 embed.FS 上把零匹配当成可解释结果

构建成功后，如果代码再用 fs.Glob 查模板，它遵循 path.Match 的通配规则。模式语法非法时返回错误；模式合法但没有文件时，通常得到空的匹配切片和空错误。应用要先判断错误，再判断数量，不能只写“没有匹配就返回错误”，否则可选模板目录会被误报成系统故障。

package web

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

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

func loadTemplates(pattern string) ([]string, error) {
	// 中文注释：先让 fs.Glob 判断模式语法，避免把非法模式伪装成空目录。
	matches, err := fs.Glob(templates, pattern)
	if err != nil {
		return nil, fmt.Errorf("模板模式无效 %q: %w", pattern, err)
	}
	if len(matches) == 0 {
		// 中文注释：合法模式的零结果可表示可选功能未启用，交给调用方决定是否降级。
		return nil, nil
	}
	return matches, nil
}

func readFirst(pattern string) ([]byte, error) {
	matches, err := loadTemplates(pattern)
	if err != nil {
		return nil, err
	}
	if len(matches) == 0 {
		// 中文注释：这里明确区分“没有模板”和“读取模板失败”，便于日志与告警分层。
		return nil, fmt.Errorf("没有找到模板: %s", pattern)
	}
	data, err := fs.ReadFile(templates, matches[0])
	if err != nil {
		// 中文注释：匹配成功不代表读取一定成功，保留底层路径和错误原因。
		return nil, fmt.Errorf("读取模板 %q 失败: %w", matches[0], err)
	}
	return data, nil
}

上面的 loadTemplates 把“模式无效”和“没有模板”分开返回；readFirst 才根据当前业务把零结果升级为错误。若模板是可选插件，可以在调用方选择默认页面；若模板是核心资源，则在这里返回明确错误。这样既不破坏 fs.Glob 的语义，也让告警具有可行动性。

发布前的 glob 目录检查清单

• 逐项检查 //go:embed 模式是否相对正确的包目录，且每项都有文件或非空目录命中。
• 确认目录模式与 * 模式的隐藏文件规则符合资源预期，不要把临时文件当成稳定入口。
• 为可选模板规定零匹配行为，为核心模板规定缺失时的错误信息。
• 使用正斜杠和合法的 path.Match 语法，不用操作系统路径拼接替代资源模式。

常见问题

//go:embed 指向空目录为什么会编译失败？

它是构建期资源声明，每个模式必须至少命中一个文件或非空目录。给目录保留普通名称的入口文件，或改成明确的文件模式，才能让资源契约稳定。

fs.Glob 返回空切片一定是错误吗？

不一定。模式合法但没有匹配时，空结果可以表示可选资源未启用；只有模式语法错误或后续读取失败时，才应按对应层次处理。

static 和 static/* 应该怎么选？

需要递归目录且遵守默认隐藏文件排除规则时选目录模式；需要按通配符精确控制直接子项时选星号模式，并检查它是否会收集不想嵌入的点文件。

什么时候使用 all: 前缀？

只有当点文件或下划线文件本身就是运行时资源时使用。它会扩大目录递归的收集范围，不适合作为“目录为空”的临时补丁。