Go 的 text/template 执行成功，但页面仍然是空的，通常不代表模板“没有运行”。更常见的原因是：输出写到了另一个 Writer、执行了不显示正文的根模板，或者 if、with、range 正好遇到了零值和空集合。排查时先观察输出长度，再检查模板入口，最后核对传入数据的形状。

官方地址：https://pkg.go.dev/text/template

先确认 Execute 真的写入了输出

不要一上来就改模板语法。先把渲染结果集中写进缓冲区，再判断错误和长度。这样可以把“没有输出”和“输出没有被响应使用”分开。

package main

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

func main() {
    const source = `
{{.Title}}
`
    tmpl, err := template.New("page").Parse(source)
    if err != nil {
        log.Fatal(err) // 解析错误要在渲染前终止，避免继续使用不完整模板。
    }

    var buf bytes.Buffer
    data := struct{ Title string }{Title: "模板诊断"}
    err = tmpl.Execute(&buf, data)
    if err != nil {
        log.Fatal(err) // 执行期字段或方法错误要保留原始错误信息。
    }

    fmt.Printf("bytes=%d\\n%s\\n", buf.Len(), buf.String()) // 长度为零时先查模板入口和空分支。
}

这里的关键不是打印内容，而是保证“执行写入的 Writer”和“后续发送给浏览器的内容”是同一个来源。若 buf.Len() 大于零而页面为空，问题多半在 HTTP 响应拼接、提前返回或覆盖响应体；若长度为零，继续查模板入口和数据分支。

模板入口和空数据分支要分开排查

使用 define 组织页面时，解析成功并不等于你执行了包含正文的那个模板。根模板可能只保存定义，正文另有名称，此时应明确调用 ExecuteTemplate。

数据本身也可能让模板安静地产生空结果。if、with 会把 nil、零值和长度为零的字符串、切片、Map 当作空；range 遍历空集合时没有迭代体输出。给列表补上 else，比在服务层猜测更直观。

const page = `{{define "body"}}

  {{if .User}}
你好，{{.User.Name}}
{{else}}
未登录
{{end}}
  {{range .Items}}
{{.}}
{{else}}
暂无数据
{{end}}
{{end}}`

tmpl, err := template.New("page").Parse(page)
if err != nil {
    return err // 先确认所有 define 块都被成功解析。
}
var buf bytes.Buffer
err = tmpl.ExecuteTemplate(&buf, "body", viewModel) // 命名模板必须使用准确名称。
if err != nil {
    return err // 将执行错误交给上层统一转为 HTTP 错误响应。
}

如果 viewModel.User 为空，页面仍会有“未登录”；如果 Items 为空，也会有“暂无数据”。这类显式状态能避免用户看到一整块空白，也方便确认模板确实走到了目标分支。

字段路径、Writer 和 HTTP 响应的三项检查

字段路径也要按真实数据结构核对：结构体字段通常从大写导出字段开始，Map key 必须与传入键一致；模板中的 .Profile.Name 不能用一个只有 Name 字段的对象替代。对 HTTP Handler，建议先在缓冲区完整渲染，成功后再写状态码、Content-Type 和正文，避免半个页面已经提交后才发现执行错误。

相关问题

Execute 返回 nil，是否说明模板一定正确？

不一定。它主要说明本次执行没有返回错误，空条件、空集合和错误模板入口都可能让可见内容为空。

什么时候必须使用 ExecuteTemplate？

当模板通过 define 声明多个命名模板，并且要明确渲染其中一个正文入口时，使用它比依赖根模板名称更可靠。

为什么同一个模板并发执行会出现内容串行混合？

模板解析结果可以并行复用，但每次执行应使用独立 Writer；共享 Writer 会让不同执行的输出互相交错。

按“输出长度—模板入口—数据分支—响应提交”的顺序排查，通常几分钟就能把空白页面缩小到一个具体边界，而不是反复修改模板标记。