Go template.Template 为什么在边界输入上得到空结果

我排查过几次“模板解析成功，但页面什么也没有”的问题，最后发现空结果通常不是 Parse 失败，而是执行目标和模板结构没有对上：根模板只有 define，if/with/range 的管道为空，或者 map 键缺失却沿用了默认的无值行为。先把这几类边界拆开，定位会快很多。

先记住：输出为空不等于执行成功。每次都同时记录执行的模板名、写入结果和 Execute 返回的 error；如果用了命名模板，再用 DefinedTemplates 或 Lookup 确认真正应该执行哪个模板。

先用最小样例定义“空结果”

Template.Execute 会把已解析的模板应用到数据并写入 io.Writer。所以排查时要分清三件事：模板正文是否真的有文本、控制结构是否进入、执行过程是否返回错误。下面的对照把普通文本、空条件和缺失键放在一起：

package main

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

func render(label, source string, data any) {
    // 先解析，再单独执行，避免把解析错误误判成空输出。
    tmpl, err := template.New(label).Parse(source)
    if err != nil {
        fmt.Printf("%s parse error: %v\n", label, err)
        return
    }

    var out bytes.Buffer
    // Execute 的 error 必须保留；输出为空时尤其不能忽略它。
    err = tmpl.Execute(&out, data)
    fmt.Printf("%s output=%q err=%v\n", label, out.String(), err)
}

func main() {
    render("plain", "hello {{.Name}}", map[string]string{"Name": "Go"})
    render("empty-if", "{{if .Enabled}}visible{{end}}", map[string]bool{"Enabled": false})
    render("missing-key", "value={{.Missing}}", map[string]string{})
}

这里的 empty-if 没有输出是正常结果，不是执行失败；而 missing-key 在默认选项下可能得到 或无值表现，取决于它是否被打印。要定位业务数据问题，建议在开发和测试阶段改成显式报错。

ParseFiles 和 define 为什么会让根模板为空

这是我最容易踩到的边界：文件里写了 {{define "page"}}...，解析没有报错，但随后直接调用根模板的 Execute，结果却是空。官方文档说明，命名定义会创建关联模板，并从当前模板的正文中移除；这时应该按名称执行。

package main

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

func main() {
    source := `{{define "page"}}标题：{{.Title}}{{end}}`
    tmpl, err := template.New("root").Parse(source)
    if err != nil {
        panic(err)
    }

    // 查看关联模板名称，先确认 page 确实已经被定义。
    fmt.Println(tmpl.DefinedTemplates())

    var out bytes.Buffer
    // 根模板正文可能为空；按命名模板执行才会得到 page 的内容。
    err = tmpl.ExecuteTemplate(&out, "page", map[string]string{"Title": "模板边界"})
    if err != nil {
        panic(err)
    }
    fmt.Println(out.String())
}

如果使用 ParseFiles，还要注意模板名称通常是文件的基础名，而不一定是你传给 template.New 的名字。执行前用 Templates() 或 Lookup("文件名") 看实际关联名称；名字不对时，优先改用 ExecuteTemplate，不要靠猜。

空管道、缺失键和 missingkey 要分开判断

if、with 和 range 都有“空值不输出”的合法语义：false、数字零、nil 指针或接口，以及长度为零的数组、切片、map、字符串，都可能让主体跳过。需要告诉用户“没有数据”时，应写 else，而不是把空白当成错误。

package main

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

func main() {
    source := `{{if .Items}}{{range .Items}}{{.}}{{end}}{{else}}没有可展示的数据{{end}}`
    tmpl, err := template.New("list").Option("missingkey=error").Parse(source)
    if err != nil {
        panic(err)
    }

    var out bytes.Buffer
    // Items 为空时走 else；缺失字段则由 missingkey=error 直接暴露。
    err = tmpl.Execute(&out, map[string]any{"Items": []string{}})
    if err != nil {
        fmt.Println("execute error:", err)
        return
    }
    fmt.Println(out.String())
}

missingkey=error 只针对 map 索引不到键的情况，不会把所有空字符串或空切片都变成错误。判断时可以用这张对照表：

一张清单完成最后排查

遇到空结果时，按这个顺序检查：第一，打印 Execute 或 ExecuteTemplate 返回值；第二，用 DefinedTemplates、Lookup 确认执行目标；第三，把空管道临时改成带 else 的表达；第四，在测试环境设置 missingkey=error；第五，确认输出缓冲区和 Writer 没有被后续逻辑清空或覆盖。这样能把“合法无输出”“执行了错误模板”和“数据缺失”分成三个独立问题。

相关问题

为什么 Parse 成功但 Execute 没有报错？

Parse 只负责语法和模板定义；空的控制分支、空根模板都可能是合法结构。执行时要检查实际输出和命名模板选择。

缺失 map 键一定会返回错误吗？

不一定。text/template 默认允许继续执行；需要强约束时，在解析前设置 missingkey=error。

什么时候用 ExecuteTemplate？

当模板包含 define、使用 ParseFiles 或需要在同一模板集合中选择不同页面时，显式传入命名模板更稳妥。