Go 的 html/template 渲染链路最好拆成三个阶段：先注册模板函数，再解析模板文本，最后把数据写入输出。函数表不完整属于注册阶段问题，括号或动作语法错误属于解析阶段问题，而字段缺失、函数运行失败或写入器报错属于执行阶段问题。把三类错误分别加上上下文，排查时就不用猜错在模板、数据还是输出端。

先把三类错误放回各自的阶段

Funcs 只负责把 Go 函数放进模板函数表。模板动作在解析时就要知道函数名是否存在，所以调用顺序应是 New → Funcs → Option → Parse。如果把 Funcs 放到 Parse 后面，模板里的 {{upper .Name}} 会在解析时被当成未知函数。

Parse 返回的是模板结构，常见错误包括未闭合的动作、管道语法错误和函数参数数量不匹配。解析成功并不代表渲染成功：数据字段可能缺失，函数也可能在执行时返回错误，最终的 io.Writer 还可能拒绝写入。

用一个渲染函数分别处理注册、解析与执行

下面的函数把错误前缀固定下来，调用方拿到日志后可以直接判断下一步。missingkey=error 让 map 中不存在的字段尽早暴露；如果业务允许缺省值，也可以改成默认策略，但要在接口约定中写清楚。

package main

import (
    "bytes"
    "fmt"
    "html/template"
    "strings"
)

func renderPage(source string, data map[string]string) (string, error) {
    // 自定义函数必须在 Parse 之前注册，否则解析阶段找不到函数名。
    funcMap := template.FuncMap{
        "upper": strings.ToUpper,
    }

    // missingkey=error 让字段缺失在执行阶段变成明确错误。
    tmpl, err := template.New("page").
        Option("missingkey=error").
        Funcs(funcMap).
        Parse(source)
    if err != nil {
        // 语法、动作或函数签名问题属于解析错误，不应继续执行。
        return "", fmt.Errorf("模板解析失败: %w", err)
    }

    var output bytes.Buffer
    // Execute 可能只写出部分内容，因此失败时不要复用这段输出。
    if err := tmpl.Execute(&output, data); err != nil {
        return "", fmt.Errorf("模板执行失败: %w", err)
    }
    return output.String(), nil
}

func main() {
    html, err := renderPage("
{{upper .Name}}
", map[string]string{"Name": "go"})
    if err != nil {
        // 上层可以按错误前缀记录指标或返回 500，而不是继续发送半成品。
        panic(err)
    }
    fmt.Println(html)
}

这个例子中，函数名写错会让 Parse 返回错误；模板写成未闭合的动作同样停在解析阶段；数据缺少 Name 时则由 Execute 返回错误。执行错误可能发生在已经写出部分内容之后，所以 HTTP 响应已经开始发送时，不要把“再补一段错误文字”当作可靠恢复方案。

多文件模板要先注册共享函数，再执行命名模板

使用 ParseFiles、ParseGlob 或 ParseFS 时，规则不变：先创建模板、设置选项、注册全部共享函数，再解析文件。解析成功后，ExecuteTemplate 还需要找到目标名称；文件名或 {{define}} 名称写错，应该把它归入命名模板执行边界，而不是重新猜测函数注册问题。

func renderNamed(w io.Writer, fsys fs.FS, data any) error {
    // 共享函数先进入函数表，所有文件解析时都可以使用它。
    tmpl := template.New("layout").Funcs(template.FuncMap{
        "trim": strings.TrimSpace,
    }).Option("missingkey=error")

    // ParseFS 失败时停止，避免拿不完整的模板集合继续响应请求。
    tmpl, err := tmpl.ParseFS(fsys, "templates/*.html")
    if err != nil {
        return fmt.Errorf("模板文件解析失败: %w", err)
    }

    // ExecuteTemplate 单独校验命名模板和数据执行过程。
    if err := tmpl.ExecuteTemplate(w, "detail.html", data); err != nil {
        return fmt.Errorf("命名模板执行失败: %w", err)
    }
    return nil
}

如果一组模板共用函数，函数注册应该集中在构造入口，不要让每个处理器各自拼一份 FuncMap。这样既能避免某个文件偶尔解析失败，也能让测试覆盖“所有模板都能解析”和“每个入口都能执行”两个不同事实。

发布前用一张表检查错误归属

html/template 会按 HTML 上下文转义动态值，适合生成服务端 HTML。只有在数据来自可信且已完成安全处理的来源时，才考虑使用特殊类型绕过默认转义；普通业务字符串不要直接转换成 template.HTML。

相关问题

为什么模板函数必须在 Parse 前注册？

解析器需要在建立模板结构时识别函数名和调用参数。Parse 后再注册只能影响后续允许的操作，不能修复已经失败的那次解析。

Execute 失败时可以继续使用已经写出的字符串吗？

不建议。执行可能已经产生部分输出，除非业务明确支持分块响应，否则应使用缓冲区，只有 Execute 完成后才把完整结果交给响应层。

什么时候用 text/template 而不是 html/template？

纯文本、邮件纯文本或配置文件可以考虑 text/template；只要结果会作为 HTML 返回，就优先使用 html/template 并保留它的上下文转义。