Go template.FuncMap 注册函数必须早于 Parse 的原因是什么

因为 Parse 会在解析模板源文本时检查函数名是否存在。模板里写了 {{formatMoney .Total}}，解析器必须先从 FuncMap 认识 formatMoney，否则函数名还没进入模板的函数表，解析就会返回 function "formatMoney" not defined。稳定顺序是 New → Funcs → Parse → Execute。

先看一个顺序错误的场景

假设订单模板需要把分转成元。下面的写法看起来只是把两行交换了位置，实际却在解析阶段失败：

package main

import (
    "fmt"
    "os"
    "text/template"
)

func formatMoney(cents int) string {
    // 将整数分转换成两位小数的金额文本，避免模板承担格式化细节。
    return fmt.Sprintf("¥%.2f", float64(cents)/100)
}

func main() {
    source := "应付：{{formatMoney .Total}}"
    tmpl, err := template.New("invoice").Parse(source)
    if err != nil {
        // 这里先返回解析错误，后面的 Funcs 根本没有机会补救当前解析。
        fmt.Println(err)
        return
    }
    tmpl = tmpl.Funcs(template.FuncMap{"formatMoney": formatMoney})
    if err := tmpl.Execute(os.Stdout, map[string]int{"Total": 1299}); err != nil {
        // Execute 仍要检查错误，因为模板执行和写入 Writer 都可能失败。
        fmt.Println(err)
    }
}

这段代码的问题不是 formatMoney 函数不能被 Go 调用，而是 Parse 还没有得到它的名字。函数注册发生在解析之后，解析器已经在上一行拒绝了模板。

正确顺序是 New、Funcs、Parse、Execute

把函数表接到模板实例后再解析，模板名称和函数调用就处于同一个构造阶段：

func renderInvoice(total int) error {
    // 先创建模板实例，再把模板允许使用的函数集中登记。
    funcs := template.FuncMap{"formatMoney": formatMoney}
    tmpl, err := template.New("invoice").Funcs(funcs).Parse("应付：{{formatMoney .Total}}")
    if err != nil {
        // 名称不存在、动作语法错误等问题在这里尽早暴露。
        return fmt.Errorf("parse invoice template: %w", err)
    }
    // Execute 只负责把已解析模板应用到数据，不再负责发现函数名。
    return tmpl.Execute(os.Stdout, map[string]int{"Total": total})
}

这里的关键不是链式调用本身，而是调用顺序。Funcs 会把函数加入模板函数表；官方文档要求模板中使用的函数在模板解析前加入。解析成功后，才适合把同一个模板用于多次执行。

Parse 后调用 Funcs，为什么有时又能成功

容易混淆的一点是：Funcs 并非在 Parse 后绝对不能调用。已经解析过的函数可以被替换，替换值会在执行时生效；但一个全新的函数名不能靠事后注册让已经失败的解析重新通过。

所以，生产代码可以在测试替换、克隆模板或构造不同运行环境时使用“解析后替换”能力，但不要把它当成“解析后补注册”的通用方案。模板文件一旦新增函数调用，构造入口仍应重新执行 Funcs → Parse。

模板拆分时按这张清单排查

使用 ParseFiles、ParseGlob 或多个关联模板时，函数表仍要挂在根模板实例上，并且早于真正读取模板内容的解析调用。遇到 “function not defined” 时，按下面顺序检查：

• 看实例：注册和解析是否作用于同一个 *template.Template，有没有在中途重新 New 出另一个实例。
• 看时机：Funcs 是否早于 Parse、ParseFiles 或 ParseGlob。
• 看名字：模板里的 formatMoney 与 map key 必须完全一致，大小写也不能凭感觉修改。
• 看签名：map 中的值必须是可调用函数，返回值要符合模板函数允许的一值或“值加 error”形式。

另外，text/template 面向可信模板作者，不会自动转义 HTML；如果模板内容来自不可信输入，应评估是否应该使用接口相同的 html/template，不要只为了让函数解析通过而忽略输出安全边界。

相关问题

只调用内置函数时也要写 FuncMap 吗？

不用。模板包自带一组预定义函数；只有自定义函数或替换默认函数时才需要维护自己的 FuncMap。

Funcs 调用后还需要重新 Parse 吗？

如果只是替换一个已经解析过的函数，后续执行可以使用替换值；如果模板新增了函数调用，则应把函数注册放回解析前并重新解析模板。

为什么 Parse 成功，Execute 却报错？

解析阶段主要确认语法和函数名等结构，数据字段为空、函数返回错误或 Writer 写入失败属于执行阶段问题，需要单独检查 Execute 的返回值。

html/template 的顺序是否一样？

一样。两者的模板函数注册与解析顺序一致；区别在于 html/template 针对 HTML 输出提供自动转义。

记住这条边界即可：Parse 负责把模板文本变成可执行结构，函数名必须在这一步之前可见；Execute 才把结构应用到具体数据。把 Funcs 放在 Parse 前，通常就是最清楚、最不容易出错的构造方式。