如何在 Go 的 html/template 中正确传递并引用基础类型变量

碧海醫心 2026-01-09 00:00:00 次阅读

go 的 html/template 模板中可直接传入 map 或基础值，但访问 map 中的字段必须使用点号前缀（如 `{{.var1}}`，而非裸变量名；否则模板会报错或渲染为空。

在 Go 的 html/template 包中，模板数据（data）本质上是一个“上下文值”（通常为 interface{} 类型）。当你传入一个 map[string]interface{} 时，模板引擎并不会自动将其键提升为全局变量——你必须显式通过.（当前作用域）来访问其字段。

例如，以下写法是错误的：

{{define "index"}}
{{var1}} is equal to {{var2}}  
{{end}}

这会导致模板执行时输出空字符串（或 panic，取决于严格模式），因为 var1 被解析为当前作用域下的字段名，而根作用域（即传入的 map）本身没有名为 var1 的方法或字段；它只是一个 map，需通过 . 显式索引。

✅ 正确写法是使用 {{.var1}} 和 {{.var2}}：

{{define "index"}}
{{.var1}} is equal to {{.var2}}
{{end}}

完整可运行示例：

package main

import (
    "html/template"
    "log"
    "net/http"
    "os"
)

func main() {
    // 方式一：从字符串解析模板（便于演示）
    tmplString := `{{define "index"}}{{.var1}} is equal to {{.var2}}{{end}}`
    tmpl, err := template.New("index").Parse(tmplString)
    if err != nil {
        log.Fatal(err)
    }

    data := map[string]interface{}{
        "var1": "value",
        "var2": 100,
    }

    // 输出到标准输出（或 HTTP 响应）
    tmpl.ExecuteTemplate(os.Stdout, "index", data) // 输出: "value is equal to 100"

    // 方式二：HTTP 服务中使用（对应原问题）
    /*
    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        w.Header().Set("Content-Type", "text/html")
        if err := tmpl.ExecuteTemplate(w, "index", data); err != nil {
            http.Error(w, err.Error(), http.StatusInternalServerError)
        }
    })
    log.Println("Server running on :8080")
    http.ListenAndServe(":8080", nil)
    */
}

⚠️ 注意事项：

. 始终代表当前数据上下文。当传入 map 时，.key 等价于 map["key"]；
若传入单个基础值（如 tmpl.Execute(w, "hello")），则 {{.}} 渲染该值，不可再用 {{.xxx}}（会报错）；
模板中不支持 JavaScript 风格的变量声明或解构赋值（如 {{with .var1 as $v}} 是非法语法）；如需简化嵌套访问，可用 {{with}}、{{range}} 或预处理结构体；
推荐在生产环境使用 template.Must() 包裹 ParseFiles，确保模板编译失败时立即 panic，避免静默错误。

总结：Go 模板无“全局变量”概念，所有数据均需通过 . 显式访问。传 map 就用 {{.key}}，传结构体就用 {{.Field}}，传原始值就用 {{.}} ——统一、明确、安全。