Go 的 text/template 变量输出为空时，先不要急着改字段名。最常见的原因是模板执行过程中的点号 . 已经换了含义：进入 range 后它代表当前元素，进入 with 后它代表被选中的值；而子模板也不会自动继承调用处的模板变量。

稳定的排查顺序是：确认 Execute 传入的根数据，再标出每个作用域会不会改变 .，然后检查字段是否导出、map key 是否存在、集合是否为空，最后给子模板显式传参。这样能把“真的没有值”和“模板上下文变了”区分开。

官方资料：https://pkg.go.dev/text/template

先确认模板开始时的根对象

模板执行时，最外层的 . 就是传给 Execute 的数据。下面的模板访问的是 Page.Title，所以执行时必须传入包含 Page 字段的对象，而不是只传一个字符串或 Page 本身。

package main

import (
    "os"
    "text/template"
)

type Page struct {
    Title string
}

type ViewData struct {
    Page Page
}

func main() {
    // 根对象决定模板最外层的点号；这里与 .Page.Title 对应。
    data := ViewData{Page: Page{Title: "作用域排查"}}
    tmpl := template.Must(template.New("page").Parse("{{.Page.Title}}\n"))

    // Execute 的错误必须保留，否则字段访问失败时只会看到空白输出。
    if err := tmpl.Execute(os.Stdout, data); err != nil {
        panic(err)
    }
}

如果把调用改成 tmpl.Execute(os.Stdout, data.Page)，模板就应该写成 {{.Title}}。这不是字段随机消失，而是根对象已经换了。排查时把“传入值的类型”和“模板最外层的访问路径”放在同一行对照，通常很快就能发现。

range 和 with 会改变点号上下文

模板里的 . 不是固定指向最初的数据。range 的循环体会把点号改成当前元素，with 的正文会把点号改成它的 pipeline 值。需要访问根对象时，用模板变量 $ 保存根引用最稳妥。

type ViewData struct {
    Title string
    Items []struct {
        Name string
    }
}

const source = `
{{$root.Title}}
{{range .Items}}
  
当前项目：{{.Name}}；页面标题：{{$root.Title}}
{{else}}
  
没有可展示的项目
{{end}}`

func render(data ViewData) error {
    // $root 在模板开始时保存根对象，避免 range 改写 . 后无法回到页面数据。
    tmpl, err := template.New("list").Parse(source)
    if err != nil {
        return err
    }
    return tmpl.Execute(os.Stdout, data)
}

进入 range .Items 后，.Name 读取当前项目，$.Title 仍读取根对象。这里还保留了 else 分支，因为空切片时循环体不会输出；如果只看到“变量为空”，先确认是否其实没有进入循环。

with 的判断也类似：pipeline 为空时不会进入正文，且 else 分支中的点号保持外层值。把一个可能为空的字段直接包进 with，要同时准备缺省文案，避免把“没有数据”误认为“字段取值失败”。

再查字段导出、map key 和变量范围

作用域正确后，再看访问对象本身。结构体字段要能被模板访问，通常应使用导出字段，例如 Title，而不是小写的 title。map 的 key 则可以使用符合模板标识符规则的键名，是否存在仍要由数据决定。

type Row struct {
    Title string // 导出字段可被 .Title 访问。
    title string // 未导出字段不要在模板中依赖。
}

data := map[string]any{
    "Row": Row{Title: "可见字段"},
    "Meta": map[string]string{"owner": "Go"},
}

const source = `{{.Row.Title}} / {{.Meta.owner}}`

func renderMap(data map[string]any) error {
    // 解析成功只代表语法成立，数据字段是否存在仍要结合执行结果判断。
    tmpl, err := template.New("map").Parse(source)
    if err != nil {
        return err
    }
    return tmpl.Execute(os.Stdout, data)
}

变量也有自己的范围：在 if、with 或 range 中声明的变量，作用域到对应的 end；模板调用不会继承调用点的变量。若变量定义在循环内部，却在循环外输出，应该把需要的值提前放到根数据，或在 Go 代码中整理成明确的 ViewModel。

子模板必须显式收到需要的数据

最容易被忽略的是 define 和 template。调用 {{template "header"}} 时，子模板拿到的是 nil 数据；想让它访问对象，应显式传入 pipeline。这样模板之间的依赖一眼可见，也不依赖调用方恰好处于哪个 range 或 with。

const source = `{{define "header"}}
{{.Title}}
{{end}}
{{template "header" .}}`

type HeaderData struct {
    Title string
}

func renderHeader(data HeaderData) error {
    // 子模板用 . 读取显式传入的 HeaderData，而不是猜测外层上下文。
    tmpl, err := template.New("page").Parse(source)
    if err != nil {
        return err
    }
    return tmpl.Execute(os.Stdout, data)
}

如果必须从列表项里调用子模板，可以传当前项；如果子模板既需要当前项又需要页面级数据，建议定义一个组合对象，或使用显式 map 传递两个字段，而不是依靠隐藏的外层状态。

用最小复现把空值原因分成四类

遇到线上模板输出为空时，可以把复杂模板缩成四个问题：根对象是什么？当前 . 是谁？字段是否可访问？模板分支是否真的执行？按下面的顺序记录，定位结果比盯着整页 HTML 更可靠。

最后再检查变量的声明范围和命名是否一致。不要把所有空白都归因于模板作用域：数据本身为零值、分支条件为 false、集合长度为零，也会得到合法但空的输出。

迁移清单：把隐式上下文改成显式数据

• 记录每次 Execute 与 ExecuteTemplate 传入的数据类型。
• 在会改变点号的 range、with 入口旁，明确写出当前 . 的含义。
• 页面级数据用 $ 或组合 ViewModel 保留，不让子模板猜测外层状态。
• 为空的切片、map 和指针都准备明确的 else 或缺省分支。
• 每个子模板都通过参数表达依赖，避免使用未传入的隐式变量。

这套方法的核心不是记住更多模板语法，而是给每个点号和变量标注“当前数据是谁”。一旦上下文边界可见，Go template 变量输出为空通常就能在一个最小片段里复现并修正。

相关问题

为什么 range 里访问不到外层字段？

因为 range 循环体中的点号变成了当前元素。用 $.Field 访问根对象，或把两层数据整理成一个组合对象。

with 为空时会发生什么？

with 的 pipeline 为空时不会执行正文，若有 else 则进入 else；应把缺省状态单独写出来。

子模板能直接使用父模板的变量吗？

不能依赖这种隐式继承。调用时传入 {{template "name" .}}，让子模板从自己的点号读取数据。