Go template.ParseFS 使用通配符时如何组织模板目录

把模板编进 embed.FS 后，template.ParseFS 的通配符不是按操作系统磁盘路径工作，而是按 fs.FS 的正斜杠路径匹配。比较稳的组织方式是：页面模板、公共片段分目录保存，//go:embed 负责把它们放进同一棵 FS，ParseFS 再用每层都写清楚的模式加载，最后用 ExecuteTemplate 指定页面入口。

先把嵌入路径和通配符分成两层

建议先按“页面入口”和“可复用片段”分目录。假设 Go 源文件与 templates 位于同一个包目录，FS 中会保留 templates/ 这个前缀：

templates/
├── pages/
│   ├── home.tmpl
│   └── account.tmpl
└── partials/
    ├── header.tmpl
    └── footer.tmpl

//go:embed 的模式相对当前 Go 源文件所在的包目录；但加载时看到的是 FS 内的路径。因此下面的两个模式不是重复配置：前者决定哪些文件被编译进程序，后者决定本次解析哪些文件。

package main

import (
    "embed"
    "html/template"
)

// templateFS 把页面和公共片段保留在同一棵只读文件树中。
//go:embed templates/pages/*.tmpl templates/partials/*.tmpl
var templateFS embed.FS

func loadTemplates() (*template.Template, error) {
    // 这里的路径相对 templateFS 根目录，不是当前进程工作目录。
    return template.ParseFS(templateFS,
        "templates/pages/*.tmpl",
        "templates/partials/*.tmpl",
    )
}

多级目录不要依赖 **，用显式模式表达边界

ParseFS 使用 path.Match 规则。templates/pages/*.tmpl 能匹配 pages 下一层的文件，但不会继续进入 pages/admin/。Go 的这套模式没有把 ** 定义成“任意深度递归”，所以多级目录应明确写出层数，例如：

func loadAllTemplates() (*template.Template, error) {
    // 每个模式都要至少命中一个文件，否则 ParseFS 返回错误。
    return template.ParseFS(templateFS,
        "templates/partials/*.tmpl",
        "templates/pages/*.tmpl",
        "templates/pages/admin/*.tmpl",
    )
}

如果目录层级经常变化，可以把模板文件统一放到一层，或者在启动时用 fs.Glob 先得到匹配结果，再把明确的文件名交给解析逻辑。不要把一个看似递归、实际不会命中的模式留到生产环境。模式中的路径也不要用 filepath.Join 拼接；io/fs 约定的是 UTF-8、无根、正斜杠路径。

用命名模板承担页面组合

通配符只负责找文件，不应该承担“哪个页面是入口”的业务含义。让每个文件用 define 暴露稳定名称，页面里再引用公共片段：

{{/* 公共片段使用稳定名称，不依赖文件名 */}}
{{define "header"}}
{{.Title}}
{{end}}

{{/* 页面入口显式调用 header，便于 ExecuteTemplate 选择 */}}
{{define "home"}}{{template "header" .}}
首页
{{end}}

func renderHome(w io.Writer, data any) error {
    tmpl, err := loadTemplates()
    if err != nil {
        // 启动阶段直接返回加载错误，避免请求时才发现模板缺失。
        return fmt.Errorf("load templates: %w", err)
    }
    // 显式指定 home，避免依赖通配符命中文件的顺序和基础文件名。
    return tmpl.ExecuteTemplate(w, "home", data)
}

如果多个目录存在同名文件，命名模板和解析模式都应保持唯一；页面入口不要只依赖 Execute 默认选择的模板名。这样新增后台页面或替换 partial 时，影响范围更容易判断。

新增模板前先做这张检查表

常见问题

templates/*.tmpl 能匹配 templates 子目录吗？

不能。* 不跨越斜杠；子目录要写成独立模式，或调整目录布局。

ParseFS 可以传绝对路径吗？

不适合这样做。它读取的是 fs.FS 的虚拟路径，应传相对 FS 根目录的无根路径。

为什么建议 ExecuteTemplate 而不是 Execute？

多个文件被解析后会形成关联模板集合。显式传入页面定义名，能把渲染入口与文件命中顺序解耦。

实际落地时，只要记住“embed 决定文件进入 FS，ParseFS 决定本次匹配，ExecuteTemplate 决定最终入口”这三个边界，多级模板目录就不容易因为一个通配符写错而在部署后才暴露问题。