Go embed 怎样用 fs.Glob 查找内嵌模板

我第一次把邮件模板改成 embed.FS 时，最容易误判的是“文件明明在项目里，为什么匹配不到”。关键在于：fs.Glob 查找的是编译时嵌入的文件树，模式相对于 embed.FS 根目录，路径统一使用斜杠。稳定写法是先用 //go:embed 嵌入模板，再用 fs.Glob(templateFS, "templates/*.tmpl") 查找，最后对空结果和坏模式分别处理。

官方文档：https://pkg.go.dev/io/fs#Glob

fs.Glob 的路径根先弄清楚

//go:embed templates/*.tmpl 在编译时把文件放进只读的 embed.FS。运行时的 fs.Glob 不会回到当前工作目录，也不会读取磁盘上的同名目录；它只看这个 FS 里已经嵌入的路径。

package main

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

// templateFS 保存编译期嵌入的模板，运行时按只读文件系统访问。
//go:embed templates/*.tmpl
var templateFS embed.FS

func main() {
    // 模式相对于 embed.FS 根目录，路径分隔符固定使用斜杠。
    matches, err := fs.Glob(templateFS, "templates/*.tmpl")
    if err != nil {
        // 这里通常是 path.ErrBadPattern，属于配置错误而不是“文件没找到”。
        log.Fatal(err)
    }
    if len(matches) == 0 {
        // 空结果要单独处理，避免启动后才发现模板集合为空。
        log.Fatal("没有找到内嵌模板")
    }
    for _, name := range matches {
        fmt.Println(name)
    }
}

这里返回的名称仍然带有 templates/ 前缀。*.tmpl 只覆盖当前目录这一层；Go 的 path.Match 没有“任意深度”的 ** 语义。如果模板分散在子目录，应该明确写出模式，或改用 fs.WalkDir 做遍历，不要把 ** 当成递归写法。

把匹配结果安全交给模板解析

查找只是第一段。实际项目里我更愿意逐个读取并保留文件名，这样解析失败时日志能指出具体模板，而不是只看到一个笼统的“模板加载失败”。

import (
    "fmt"
    "io/fs"
    "path"
    "text/template"
)

func loadTemplates(fsys fs.FS, pattern string) (*template.Template, error) {
    // 模式来自固定配置；不要把用户输入直接当作文件系统查询模式。
    names, err := fs.Glob(fsys, pattern)
    if err != nil {
        return nil, fmt.Errorf("模板匹配失败 %q: %w", pattern, err)
    }
    if len(names) == 0 {
        return nil, fmt.Errorf("模板模式 %q 没有匹配文件", pattern)
    }

    root := template.New("root")
    for _, name := range names {
        // 使用基础名避免把 FS 路径直接当成模板名。
        data, err := fs.ReadFile(fsys, name)
        if err != nil {
            return nil, fmt.Errorf("读取模板 %q: %w", name, err)
        }
        if _, err := root.New(path.Base(name)).Parse(string(data)); err != nil {
            return nil, fmt.Errorf("解析模板 %q: %w", name, err)
        }
    }
    return root, nil
}

如果只需要标准的批量解析，也可以使用 template.ParseFS(templateFS, "templates/*.tmpl")；但无论哪种写法，都要把“无匹配”“读取失败”“语法解析失败”分开。这样部署包漏文件时，排查方向不会被错误日志带偏。

输入模式是配置边界，不是用户查询接口

从安全角度看，资产是编译进二进制的模板，攻击路径并不是“读到服务器任意文件”，而是外部输入影响模式后造成异常、空模板集合或错误信息放大。embed.FS 本身是只读且限定在嵌入内容内，但这不等于可以把任意字符串放心交给 fs.Glob。

我的检查清单是：模式是否以 FS 中的实际目录开头；是否误用了反斜杠或 **；是否允许空结果继续启动；日志是否包含具体文件名；模板模式是否来自白名单配置。最后一项尤其重要：如果确实要支持多套模板，用枚举映射到固定模式，比直接接受请求参数更容易审计。

常见问题

fs.Glob 匹配不到嵌套目录怎么办

先确认嵌入模式是否把子目录纳入 FS，再检查模式是否只写了一层。templates/*.tmpl 不会递归匹配更深目录。

空匹配为什么没有返回 error

这是 API 的设计：合法模式没有文件时返回空结果；只有模式本身格式错误才返回错误。因此应用要主动把空结果当作配置检查项。

fs.Glob 会读取磁盘上的模板吗

对 embed.FS 不会。它只访问编译时嵌入的数据；若要读取磁盘目录，需要显式传入另一个实现了 fs.FS 的文件系统。