我在把一组 Go 文本模板从单段字符串改成“主模板 + 多个命名模板”时，最先遇到的不是渲染格式问题，而是调用方不知道某个名称到底有没有定义。这个场景里，text/template.Template.Lookup 的职责很窄：按名称查找关联模板，找到时返回 *Template，找不到时返回 nil。它适合放在执行前的存在性检查，不负责替代解析或执行错误处理。

官方文档：https://pkg.go.dev/text/template#Template.Lookup

先划清从旧模板到命名模板的范围

旧代码常把整段文本直接交给 Parse，随后调用 Execute。一旦模板数量增加，调用方会开始依赖名称，例如把页头、列表和页脚拆成可复用片段。此时应该先确认模板组装链是否完成，再确认每个必需名称是否存在。

这张区分表是迁移时最值得保留的边界：Lookup 没有返回错误，不代表模板组装一定成功；它只告诉你当前模板集合里是否能找到指定名称。

用 Lookup 判断名称，而不是猜正文

下面的例子把两个命名模板放入同一个模板集合，再检查调用方真正需要的名称。注意 Lookup 返回的是模板指针；判断存在性时直接比较 nil 即可，不要通过模板正文是否为空来推断。

package main

import (
    "fmt"
    "text/template"
)

func requireTemplate(t *template.Template, name string) error {
    // Lookup 只负责按名称查询，找不到时返回 nil。
    if t.Lookup(name) == nil {
        return fmt.Errorf("required template %q is not defined", name)
    }
    return nil
}

func main() {
    // define 把片段注册到同一个模板集合中，Parse 的错误必须先处理。
    root, err := template.New("page").Parse(`{{define "header"}}
{{.Title}}
{{end}}
{{define "body"}}
{{.Text}}
{{end}}`)
    if err != nil {
        // 解析失败时不要继续做名称检查，否则排查信息会被掩盖。
        panic(err)
    }

    for _, name := range []string{"header", "body", "footer"} {
        // 缺失名称属于配置问题，和 ExecuteTemplate 的数据错误分开处理。
        if err := requireTemplate(root, name); err != nil {
            fmt.Println(err)
        }
    }
}

这里 header 和 body 能查到对应对象，footer 则返回 nil。即使某个命名模板的正文暂时为空，只要它已经被定义，存在性检查仍然可以通过；反过来，正文看起来像“应该存在”，也不能代替名称查询。

把 Parse、define 和执行入口接成一条链

实际迁移中，我会把名称检查放在渲染入口之前，而不是散落在每次输出之后。这样做的好处是：模板配置不完整时尽早失败，执行函数只接收已经满足最小结构的模板集合。

func renderPage(data struct {
    Title string
    Text  string
}) (string, error) {
    // 先解析并完成命名模板注册，任何语法问题都在这里返回。
    tmpl, err := template.New("page").Parse(`{{define "header"}}
{{.Title}}
{{end}}
{{define "body"}}
{{.Text}}
{{end}}`)
    if err != nil {
        return "", fmt.Errorf("parse page templates: %w", err)
    }

    // 执行前集中检查必需模板，避免名称缺失变成晚到的渲染故障。
    for _, name := range []string{"header", "body"} {
        if tmpl.Lookup(name) == nil {
            return "", fmt.Errorf("template %q is missing", name)
        }
    }

    var out bytes.Buffer
    // ExecuteTemplate 负责把数据交给指定模板，数据错误在此处单独返回。
    if err := tmpl.ExecuteTemplate(&out, "body", data); err != nil {
        return "", fmt.Errorf("execute body template: %w", err)
    }
    return out.String(), nil
}

这个片段展示的是职责分层，不是把所有模板都硬编码在业务函数里。生产代码可以把模板集合放进初始化结构，把必需名称放进配置，并在构造阶段完成同样的检查。需要注意：示例还需要导入 bytes，并在使用处保留 fmt；这里省略了重复的包声明，重点是错误边界。

迁移后按三项回归清单检查

从直接执行根模板迁移到命名模板后，我会用三项小清单收尾：

• 解析失败是否立即返回，并保留原始错误上下文？
• 所有必需名称是否在同一个模板集合里完成 Lookup 检查？
• 调用 ExecuteTemplate 后，数据访问或输出写入错误是否仍按执行错误处理？

如果只需要判断“这个名称有没有定义”，用 Lookup(name) != nil 就够了；如果需要知道为什么不能渲染，还要分别保留 Parse 和 ExecuteTemplate 的 error。这也是我在模板迁移中最不愿意省略的两层信息。

常见问题

Lookup 找不到名称时会返回 error 吗？

不会。它返回 *Template，找不到时返回 nil。需要错误文本时由调用方根据名称补充上下文。

已经 Parse 成功，为什么 Lookup 还是 nil？

常见原因是名称没有通过 define 注册到当前模板集合，或者查询时使用了不同的名称。解析成功只说明模板文本合法，不等于所有业务约定的名称都存在。

Lookup 通过后还可能执行失败吗？

可能。模板对象存在只解决了名称问题，数据字段访问、函数调用或输出写入仍可能让 ExecuteTemplate 返回错误。