Go embed.FS 读取内嵌模板的路径组织

用 embed.FS 读取内嵌模板时，最稳妥的规则只有一句：先确定当前文件系统的根，再按这个根写读取路径和 ParseFS 模式。如果保留原始 embed.FS，路径要带 templates/；如果已经通过 fs.Sub 把 templates 设为新根，后续就不能再重复这个前缀。

官方文档：https://pkg.go.dev/embed；模板接口：https://pkg.go.dev/html/template。

路径为什么会在嵌入后保留下来

//go:embed 的模式相对声明它的 Go 源文件所在包目录匹配。假设包内有 templates/layout.html 与 templates/home.html，使用 //go:embed templates/*.html 后，embed.FS 里保存的名称仍然是 templates/layout.html 和 templates/home.html，并不会自动去掉目录。

这也是路径报错最常见的来源：开发者看到文件位于 templates 目录，既在 fs.Sub 中指定一次，又在后续模式中再写一次，最终实际查找的是不存在的 templates/templates/*.html。

两种组织方式只选一种

第一种方式是保留目录前缀，直接把原始 embed.FS 交给 template.ParseFS。这种写法直观，适合模板只在一个包中使用的项目：

package webui

import (
    "embed"
    "html/template"
)

//go:embed templates/*.html
var files embed.FS

func loadTemplates() (*template.Template, error) {
    // 原始 embed.FS 保留 templates 前缀，因此模式也必须带此前缀。
    return template.ParseFS(files, "templates/*.html")
}

第二种方式是先用 fs.Sub 建立子文件系统。它把 templates 变成新的根，后续调用只看到这个目录内部的名称，适合把模板文件系统交给其他包或测试代码：

package webui

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

//go:embed templates/*.html
var files embed.FS

func loadTemplates() (*template.Template, error) {
    // 把 templates 目录提升为新根，后续路径不再重复 templates。
    views, err := fs.Sub(files, "templates")
    if err != nil {
        return nil, err
    }

    // 子文件系统根下直接匹配 HTML 文件。
    return template.ParseFS(views, "*.html")
}

ParseFS 的模式要遵循 io/fs 路径

embed.FS 实现的是 io/fs 文件系统接口。这里的名称统一使用正斜杠，根目录下的名称不能以 / 开头，也不能包含 ..。因此不要把操作系统绝对路径或 Windows 反斜杠拼进模式。

ParseFS 接受 glob 模式，而且每个模式都必须至少匹配一个文件。原始文件系统写 templates/*.html，子文件系统写 *.html；如果写成 /templates/*.html，即使磁盘上确实有这些文件，内嵌文件系统也不会把它当作有效名称。

目录负责组织，define 负责稳定模板名

ParseFS 解析多个文件时，模板文件的基础名会参与模板命名；不同目录出现相同基础名时，后解析的文件可能覆盖前一个。工程里更稳妥的做法，是让目录只负责组织文件，再在模板内容中用 {{define "page/home"}} 这类明确名称定义可执行模板。

调用时执行业务模板名，而不是猜测目录是否属于模板名：

func renderHome(t *template.Template, data any) error {
    // ExecuteTemplate 使用 define 声明的稳定名称，不依赖磁盘目录层级。
    return t.ExecuteTemplate(outputWriter, "page/home", data)
}

如果没有使用 define，应至少保证被解析文件的基础名唯一，例如不要同时放置 admin/index.html 和 public/index.html 后再依赖自动名称。对 HTML 页面应使用 html/template，它会按 HTML 上下文处理数据转义；只有生成纯文本时才考虑 text/template。

出错时先检查这三个边界

路径问题不需要靠反复改字符串碰运气，可以按错误落点快速判断：

• pattern matches no files：先看 go:embed 模式是否相对包目录，并确认模式没有前导斜杠。
• file does not exist：检查是否在 fs.Sub 后仍保留了 templates/ 前缀，或把原始文件系统误当成子文件系统。
• template ... is undefined：检查 ExecuteTemplate 使用的是 define 名称还是文件基础名，并排除同名文件覆盖。

func inspectEmbeddedNames() error {
    // ReadDir 读取的是 embed.FS 内部目录，可直接确认编译进来的文件名。
    entries, err := files.ReadDir("templates")
    if err != nil {
        return err
    }
    for _, entry := range entries {
        // 这里只记录名称；生产代码可接入项目自己的日志组件。
        log.Printf("embedded template: %s", entry.Name())
    }
    return nil
}

迁移现有项目时怎么选

已有代码如果到处写着 templates/xxx.html，先保留原始 embed.FS，把运行时磁盘读取替换为 ParseFS，改动最小。等模板加载集中到一个包后，再考虑统一使用 fs.Sub，让调用方只处理根下文件名。

最终只需记住四个对应关系：go:embed 决定哪些文件进入二进制，embed.FS 保存相对包目录的名称，fs.Sub 可以改变调用方看到的根，ParseFS 的模式必须相对当前根。把这四层写清楚，开发环境与发布后的二进制就会使用同一套路径规则。

相关问题

go:embed 能使用绝对路径吗？

不能。模式相对当前包目录，且不能用 .. 跨出包目录。需要嵌入的资源应放在该包目录或其子目录中。

为什么本地文件存在，ParseFS 仍提示匹配不到？

ParseFS 读取的是已经进入 embed.FS 的文件，不是运行时磁盘。应同时检查编译期嵌入模式和调用时的文件系统根。

模板很多时能直接嵌入整个目录吗？

可以嵌入目录树，但仍应明确是否需要隐藏文件、下划线文件以及子目录。生产项目通常使用受限模式，只把实际需要的模板编入二进制。