Go html/template ParseFS 怎么从嵌入文件加载页面

把 Go 服务打成一个二进制后，模板文件仍然留在服务器目录里，最容易在换工作目录、制作容器镜像或发布压缩包时出问题。这个场景可以用 embed.FS 和 html/template.ParseFS 收拢：前者把模板放进程序，后者从实现了 fs.FS 的只读文件系统读取匹配文件。关键不是把路径写得更复杂，而是让嵌入路径、glob 模式和最终模板名保持同一套约定。

最小可用组合是 //go:embed templates/*.html、template.New("page").ParseFS(views, "templates/*.html") 和 ExecuteTemplate。解析放在启动阶段，渲染时只传数据；不要再按操作系统文件路径去找模板。

先把嵌入根目录和模板文件对齐

假设目录如下，main.go 与 templates 位于同一层：

webapp/
├── main.go
└── templates/
    ├── home.html
    └── layout.html

声明时使用相对于 main.go 的路径，运行时传给 ParseFS 的模式也使用嵌入文件系统里的斜杠路径。两处看起来都叫 templates/*.html，但前者决定哪些文件进入二进制，后者决定哪些文件参与解析。

package main

import (
    "embed"
    "html/template"
)

// views 保存与 main.go 同目录下的模板，发布后不依赖外部文件。
//go:embed templates/*.html
var views embed.FS

var pageTemplates = template.Must(
    // ParseFS 使用 fs.FS 内部路径，而不是 os 工作目录。
    template.New("pages").ParseFS(views, "templates/*.html"),
)

embed.FS 是只读值，也实现 fs.FS，所以可以直接交给 ParseFS。如果模板目录在 internal/web/templates，就要同时调整 embed 声明和 ParseFS 模式；只改其中一处，通常会得到“没有匹配文件”的解析错误。

用 ParseFS 解析，再用 ExecuteTemplate 输出

解析成功后，模板对象已经保存了匹配到的页面定义。HTTP 请求只负责准备数据并执行，不应每次请求重新读磁盘或重新解析。下面的 handler 使用文件名 home.html 作为执行名称：

type HomeData struct {
    Title string
    Items []string
}

func home(w http.ResponseWriter, r *http.Request) {
    data := HomeData{
        Title: "项目首页",
        Items: []string{"嵌入模板", "稳定部署"},
    }

    // ExecuteTemplate 的名称必须对应解析后的模板名；失败时不要继续写成功响应。
    if err := pageTemplates.ExecuteTemplate(w, "home.html", data); err != nil {
        http.Error(w, "template execution failed", http.StatusInternalServerError)
        return
    }
}

完整程序还需要导入 net/http。模板中的 {{.Title}} 和 {{range .Items}} 会按 html/template 的上下文自动转义；不要为了让一段字符串“原样变成 HTML”而把不可信输入转换成 template.HTML。

如果采用布局文件，可以在 layout.html 中写 {{define "layout"}}，再用 ExecuteTemplate(w, "layout", data)。此时执行名不一定是文件名，必须以模板定义名为准。

四个边界能快速定位 ParseFS 失败

排查时先看编译期嵌入范围，再看解析模式，最后看执行名称和数据。不要先修改 chdir 或在容器中挂载一个“刚好能找到”的模板目录，那会掩盖二进制是否真正自包含的问题。

常见问题与部署检查

ParseFS 能不能读取任意绝对路径？

不能。它读取传入的 fs.FS，路径必须是该文件系统支持的内部路径；embed.FS 不会因为工作目录变化而看到宿主机文件。

为什么 ParseFS 成功，ExecuteTemplate 却失败？

两者检查的对象不同：前者验证文件能否按模式解析，后者按模板名称查找并执行。使用 define 时，执行名应是定义名而不是文件名。

模板中是否还能使用自定义函数？

可以，但要在 ParseFS 之前调用 Funcs 注册函数；解析阶段需要认识模板里出现的函数名。

嵌入模板后还需要把 templates 目录复制进镜像吗？

只要所有页面都来自 embed.FS，运行时不需要再复制同一份模板。保留外部目录反而容易让部署脚本误以为程序依赖当前目录。

最后检查四件事：embed 声明覆盖了目标文件，ParseFS 模式能匹配它们，ExecuteTemplate 使用了真实模板名，错误路径不会继续写入成功响应。这样页面就真正随 Go 二进制发布，而不是把文件路径问题推迟到上线后。