Go 的 html/template 需要自定义模板函数时，最稳妥的顺序是：先创建模板，再调用 Funcs 注册函数，最后执行 Parse、ParseFiles 或 ParseGlob。这样解析器能识别动作中的函数名，运行阶段再把数据交给 Execute。官方包地址：https://pkg.go.dev/html/template。

把 FuncMap 当作模板解析前的依赖声明。注册晚了，解析阶段就无法建立函数调用；函数签名不合规，则应在启动配置阶段尽早暴露，而不是等页面执行才猜原因。

一、先把注册顺序固定下来

Funcs 修改模板的函数映射，而 Parse 会读取模板动作并检查函数名。官方文档明确要求在解析前调用 Funcs。因此下面这种链式写法适合放在初始化或请求处理器之外，避免每次请求重复建立模板：

package main

import (
	"html/template"
	"log"
	"os"
	"strings"
)

func main() {
	funcs := template.FuncMap{
		"upper": func(s string) string {
			// 模板只负责展示；这里保留一个简单、可预测的转换函数。
			return strings.ToUpper(s)
		},
	}

	// 先注册函数，再解析模板动作，避免 Parse 看不到 upper。
	tmpl, err := template.New("page").Funcs(funcs).Parse(`
{{upper .Title}}
`)
	if err != nil {
		// 解析错误属于启动配置问题，应立即终止初始化。
		log.Fatal(err)
	}
	if err := tmpl.Execute(os.Stdout, map[string]string{"Title": "go"}); err != nil {
		// Execute 可能返回数据访问、函数执行或 Writer 错误。
		log.Fatal(err)
	}
}

这里把初始化、解析和执行分开看，排障时先确定是哪一层失败。

二、函数签名要在注册时就能被接受

模板函数必须是真正的函数值，返回值需要符合模板调用约定。最常用的是返回一个结果，或者返回结果与 error。后者适合把格式化失败、查找不到数据等可预期问题传回 Execute。

import "fmt"

func formatPrice(cents int) (string, error) {
	// 负数不是本示例允许的金额，返回错误让 Execute 停止当前渲染。
	if cents 

如果把普通字符串、带有不支持返回形态的函数或不可作为模板函数名的键放进 FuncMap，Funcs 会触发 panic。生产代码可以在固定初始化路径使用 template.Must，但动态配置仍应保留显式错误处理，避免把外部输入变成进程级崩溃。

三、多文件解析仍然复用同一个函数表

ParseFiles 和 ParseGlob 只是一次加载多个模板文件，并不会改变函数注册规则。先在根模板上注册，再调用批量解析；不要让某个文件先被解析、另一个文件才补函数。

import "strings"

func loadTemplates(pattern string) (*template.Template, error) {
	funcs := template.FuncMap{
		"asset": func(name string) string {
			// 统一拼接静态资源路径，避免模板文件各写一套规则。
			return "/static/" + strings.TrimPrefix(name, "/")
		},
	}

	// 根模板持有函数表，Glob 载入的命名模板共享这份解析上下文。
	return template.New("layout").Funcs(funcs).ParseGlob(pattern)
}

这里的边界是“模板结构复用”，不是把请求数据放进全局变量。函数表可以在应用启动时固定；每次执行仍应通过 Execute 传入本次请求的数据。

四、Parse 错误和 Execute 错误要分开处理

函数名不存在、动作语法错误，通常在 Parse 阶段暴露；数据字段不匹配、函数内部返回错误以及写出失败，则可能在 Execute 阶段出现。Execute 出错时已经写出的内容不一定会回滚，因此 HTTP 响应最好先写入缓冲区，成功后再提交给客户端。

还要注意并发边界：一个已经解析完成的模板可以被并发执行，但多个执行不要共享会交错写入的同一个 io.Writer。函数本身也应尽量保持无共享可变状态，否则模板看似安全并发，业务数据仍可能互相污染。

五、上线前用这张清单复查

相关问题

Parse 之后还能补 FuncMap 吗？

不应这样设计。官方约定是解析前注册；需要新增函数时重新建立或克隆一份尚未完成解析的模板配置，再按正确顺序解析。

html/template 和 text/template 的 FuncMap 顺序不同吗？

顺序规则相同，但 html/template 还会针对 HTML、CSS、JavaScript 和 URI 上下文做自动转义。本文只讨论函数注册边界，不能把自定义函数当成绕过安全转义的手段。