Go embed.FS 配合 fs.Glob 怎么批量加载模板

如果模板已经随程序一起发布，推荐把目录交给 embed.FS，再用 fs.Glob 收集匹配文件，最后一次性传给 html/template。关键点有两个：//go:embed templates 负责把目录树放进二进制，fs.Glob 负责运行时按模式找文件；它不会把 ** 当成任意层级通配符。

先把模板目录嵌入成一个只读文件系统

embed.FS 实现了 io/fs.FS，因此它可以交给标准库中接受 fs.FS 的 API。嵌入目录时，//go:embed templates 会把该目录下的文件树放进程序；它与开发机上的工作目录无关，部署时不会因为当前目录变化而找不到模板。

下面的目录假设为 templates/home.tmpl、templates/layout.tmpl 和 templates/admin.tmpl：

package main

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

// 把 templates 目录作为只读文件系统嵌入二进制。
//go:embed templates
var templateFS embed.FS

func loadTemplates() (*template.Template, error) {
    // 只匹配 templates 目录这一层的 .tmpl 文件。
    matches, err := fs.Glob(templateFS, "templates/*.tmpl")
    if err != nil {
        return nil, fmt.Errorf("匹配模板模式失败: %w", err)
    }
    if len(matches) == 0 {
        return nil, fmt.Errorf("没有找到模板: templates/*.tmpl")
    }

    // matches 是嵌入文件的完整 fs 路径，直接批量解析。
    parsed, err := template.New("site").ParseFS(templateFS, matches...)
    if err != nil {
        return nil, fmt.Errorf("解析模板失败: %w", err)
    }
    return parsed, nil
}

func main() {
    if _, err := loadTemplates(); err != nil {
        log.Fatal(err)
    }
}

这里没有把 templateFS 转成操作系统路径。fs.Glob 返回的正是 io/fs 里的逻辑路径，后续交给 ParseFS 时应保持同样的斜杠和目录前缀。

fs.Glob 的返回值要分成三种情况

不要只写 matches, _ := fs.Glob(...)。这个函数的返回值包含重要边界：

fs.Glob 会忽略遍历目录时遇到的普通文件系统错误，唯一可能返回的错误是非法模式。因此生产代码仍应检查 err，并对空列表做业务判断，否则模板漏打包时可能直到请求到达页面才暴露问题。

批量解析时，模式范围决定了模板集合

templates/*.tmpl 中的星号不跨越斜杠，所以它只匹配 templates 根目录下的模板。若有一层子目录，例如 templates/admin/user.tmpl，可以显式使用 templates/*/*.tmpl，也可以分两次收集后合并：

// 先匹配根目录，再匹配固定的一层子目录。
rootMatches, err := fs.Glob(templateFS, "templates/*.tmpl")
if err != nil {
    return nil, fmt.Errorf("匹配根模板失败: %w", err)
}

adminMatches, err := fs.Glob(templateFS, "templates/admin/*.tmpl")
if err != nil {
    return nil, fmt.Errorf("匹配后台模板失败: %w", err)
}

allMatches := append(rootMatches, adminMatches...)
if len(allMatches) == 0 {
    return nil, fmt.Errorf("模板集合为空")
}

// 传入具体文件名，避免 ParseFS 再次扩大匹配范围。
parsed, err := template.New("site").ParseFS(templateFS, allMatches...)
if err != nil {
    return nil, fmt.Errorf("批量解析模板失败: %w", err)
}

不要把 templates/**/*.tmpl 当作递归写法。Go 的 path.Match 没有 globstar 规则，它不会像某些 shell 工具那样自动遍历任意层级。目录深度不固定时，应使用 fs.WalkDir 收集后缀为 .tmpl 的文件，再把收集到的具体路径交给解析器。

上线前用这份检查清单收口

• 嵌入指令是否覆盖了实际模板目录，而不是只覆盖本地当前目录中的文件。
• 模式中的路径是否使用正斜杠，通配符是否跨越了不允许跨越的目录层级。
• 是否区分“无匹配”和“非法模式”，并在启动阶段尽早暴露必选模板缺失。
• 是否把 fs.Glob 返回的逻辑路径直接交给 ParseFS，没有混入 filepath.Join 生成的系统路径。

常见问题

embed.FS 能直接交给 template.ParseFS 吗？

可以。embed.FS 实现 fs.FS，template.ParseFS 接受这个接口。若要先记录匹配清单或自定义空集合策略，再用 fs.Glob 收集具体路径。

没有匹配文件时一定要返回错误吗？

不一定。必选页面模板建议在启动阶段报错；可选主题模板可以记录日志并继续，但不能把空集合误当成解析成功。

为什么不直接用操作系统的 filepath.Glob？

嵌入资源使用 io/fs 的逻辑路径，不保证对应部署机上的真实文件。fs.Glob 能直接作用于 embed.FS，路径语义也更稳定。

官方参考：https://pkg.go.dev/io/fs、https://pkg.go.dev/embed。需要支持任意深度目录时，把“模式匹配”改成“遍历后筛选具体路径”，再继续复用同一套批量解析逻辑。