embed.FS 配合 fs.Glob 加载内置模板的设计要点

如果模板会随 Go 程序一起发布，比较稳妥的做法是把模板目录声明成 embed.FS，再用 fs.Glob 明确检查模式命中了哪些文件。真正解析模板时，可以把同一个 embed.FS 交给 html/template.ParseFS。这样，嵌入、匹配和解析各自负责一件事：embed.FS 提供只读文件系统，fs.Glob 提供匹配清单与模式错误，ParseFS 负责模板语法。

需要注意的是，fs.Glob 不是模板解析器，也不会替你发现错误的模板内容；它只按 path.Match 规则找路径。若项目不需要输出清单或启动前诊断，ParseFS 本身已经能接受 glob 模式，可以少做一次遍历。

先把嵌入路径和文件系统边界定清楚

//go:embed 的模式相对于声明变量的包目录解释，嵌入后的路径使用正斜杠。目录模式会递归包含子树，但普通目录模式会排除名称以点号或下划线开头的文件；如果这类文件确实属于模板资源，需要在设计阶段显式考虑 all: 前缀。embed.FS 是只读的 fs.FS，运行时不会回到源码目录读取文件。

package templates

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

// templateFiles 把当前包下的 templates 子树编译进程序。
//go:embed templates
var templateFiles embed.FS

func listTemplates() ([]string, error) {
	// 模式使用嵌入文件系统里的 slash 路径，不使用 filepath.Join。
	matches, err := fs.Glob(templateFiles, "templates/*.tmpl")
	if err != nil {
		// 这里主要捕获非法 glob 模式，保留原错误便于定位配置。
		return nil, fmt.Errorf("匹配内置模板: %w", err)
	}
	if len(matches) == 0 {
		// 空匹配不是 fs.Glob 的错误，是否允许由启动策略决定。
		return nil, fmt.Errorf("没有匹配到内置模板")
	}
	return matches, nil
}

这段代码把“没有匹配到文件”提升为业务错误，是因为模板应用通常希望在启动阶段尽早失败。若空匹配在你的场景里代表可选功能，可以返回空切片，把判断交给调用方。不要把 fs.Glob 返回的空结果误认为底层磁盘读取失败；官方接口只把坏模式作为可能返回的错误，文件系统读取错误会被 glob 逻辑忽略。

fs.Glob 适合做清单和启动前诊断

当程序需要记录“本次内置了哪些模板”、检查某个主题目录是否完整，或者要给出比模板解析错误更具体的启动日志时，先调用 fs.Glob 很有价值。匹配结果是嵌入文件系统里的逻辑路径，后续读取时应继续使用这些路径，不要把它们拼成当前机器的绝对路径。

glob 模式里，* 只代表单层路径片段；需要匹配子目录时要把目录层级写进模式，或者针对每个模板组各自调用一次。模式中的分隔符是 /，这也是 io/fs 约定的路径形式，跨平台时不要用操作系统路径分隔符替换它。

模板解析时再决定是否保留 Glob 结果

如果只想解析某一组模板，html/template.ParseFS 可以直接接收文件系统和模式，不必把 fs.Glob 的结果再转换成另一套输入。只有当你需要在解析前输出清单、区分空匹配，或为多个模板组建立索引时，才值得保留显式的匹配步骤。

package templates

import (
	"fmt"
	"html/template"
	"io"
)

func parsePageTemplates() (*template.Template, error) {
	// ParseFS 直接使用嵌入 FS 和同一套 slash glob 模式。
	tmpl, err := template.ParseFS(templateFiles, "templates/*.tmpl")
	if err != nil {
		// 这里处理的是模板语法、定义名或匹配相关的解析失败。
		return nil, fmt.Errorf("解析页面模板: %w", err)
	}
	return tmpl, nil
}

func render(w io.Writer, tmpl *template.Template, name string, data any) error {
	// 使用 ExecuteTemplate 明确选择定义名，避免依赖调用方猜测根模板。
	return tmpl.ExecuteTemplate(w, name, data)
}

上例省略了业务输出器的创建，只强调边界：ParseFS 读取的是 fs.FS 中的路径，ExecuteTemplate 使用模板定义名执行。若模板之间有同名定义，要在项目约定里明确命名，否则“匹配到了文件”不等于“执行时选对了模板”。

三种方案怎么选

如果目标是单文件部署、模板随版本一起发布，优先使用第一种或第二种方案。第一种多一个清单检查，但能把资源缺失尽早暴露；第二种代码更短，适合模板固定且不需要单独展示匹配结果的服务。只有明确需要运营侧替换模板时，才把读取边界放回磁盘，并接受由此带来的部署约束。

几个容易混淆的失败边界

• glob 语法错误：fs.Glob 只会把坏模式作为错误返回，模式要和 path.Match 规则一致。
• 空匹配：空切片不代表调用失败；是否启动、降级或使用默认模板，应由业务策略明确决定。
• 模板解析错误：匹配到文件后，模板动作、定义名或函数调用仍可能导致 ParseFS 失败。
• 隐藏文件：//go:embed templates 与 //go:embed templates/* 对点号或下划线文件的包含规则不同，不能只看目录名猜结果。
• 运行时改文件：embed.FS 是编译时资源，修改源码目录不会改变已构建程序里的内容。

收口成一个可复用的加载约定

工程里最重要的不是把两个 API 串起来，而是先写清楚模板资源的契约：模板都放在哪个包目录、模式允许几层目录、空匹配是否阻止启动、模板定义如何命名。然后让加载函数只接收固定的 fs.FS 和模式，把清单检查与解析错误分别包装，调用方就能在日志里快速区分“资源没有嵌入”“模式写错”和“模板内容无效”。

可以用下面的判断收尾：

• 需要知道匹配了哪些文件：保留 fs.Glob，再把同一个 embed.FS 交给 ParseFS。
• 模板固定且只关心解析：直接使用 ParseFS，减少一次显式遍历。
• 需要热更新：不要误用 embed.FS，改用明确的磁盘文件系统并补上部署约束。
• 需要跨平台：统一使用 io/fs 的 slash 路径，不把 filepath 的本地分隔符带入嵌入路径。

常见问题

fs.Glob 没匹配到文件时一定会返回错误吗？

不一定。没有匹配项通常得到空结果；坏模式才会返回模式错误。若模板是启动必需品，应由加载函数主动把空结果转换成带上下文的业务错误。

已经用了 ParseFS，为什么还要调用 fs.Glob？

只有在需要模板清单、空匹配诊断、分组索引或更早的启动检查时才值得调用。固定模板集合且不需要这些信息时，直接 ParseFS 更简单。

embed.FS 能不能在程序运行时替换模板？

不能把它当成可写目录。它承载的是构建时嵌入的只读文件；若业务要求运行时换模板，应把文件放在明确的磁盘路径或其他外部存储中，并单独设计更新、权限和回滚策略。