在Go text/template 中使用 {{range}} 时，.（dot）会自动切换为当前迭代项，导致无法直接访问原始数据中的顶层字段（如 .lang）；解决方法是使用 $ 显式引用初始传入的数据根对象。
在go `text/template` 中使用 `{{range}}` 时，`.`（dot）会自动切换为当前迭代项，导致无法直接访问原始数据中的顶层字段（如 `.lang`）；解决方法是使用 `$` 显式引用初始传入的数据根对象。
在 Go 模板开发中，{{range .users}} 是高频操作，但也是新手最容易踩坑的场景之一：一旦进入 range 循环，模板的当前上下文（即 .）就从原始数据结构（如 map[string]interface{}）切换为当前遍历的元素（例如 User 实例），此时再写 {{.lang}} 就会报错 can't evaluate field lang in type User——因为 lang 并不存在于 User 结构体中。
✅ 正确解法：使用 $ 引用初始执行上下文
Go 模板规范明确规定：$ 始终代表调用 Execute() 时传入的原始数据参数（即最外层的 data argument）。无论嵌套多少层 range 或 with，$ 的值恒定不变。
以你提供的代码为例：
renderer.HTML(w, http.StatusOK, "users/index", map[string]interface{}{
"lang": chi.URLParam(r, "lang"),
"users": users,
})
对应模板应写作：
{{ range .users }}
{{ end }}
注意关键点：{{ $.lang }} 中的 $ 表示“回到根数据”，.lang 则是从该根对象中取键 "lang" 的值；而 {{ .Username }} 中的 . 是当前 User 实例，因此可正常访问其导出字段（首字母大写！）。
⚠️ 注意事项：
- 所有结构体字段必须首字母大写（如
Username✅，username❌），否则text/template通过反射无法访问； - 若使用
map[string]interface{}传参，{{$.lang}}成立，但{{.lang}}在range内失效——因为.已变为map的 value（即User），而非原map； - 多层嵌套时（如
{{range .Groups}}{{range .Users}}），仍可用$访问最外层数据，也可用$$（不推荐）、或显式赋值提升可读性：{{ $lang := $.lang }} {{ range .users }} <a href="/%7B%7B%24lang%7D%7D/user">{{ .Username }}</a> {{ end }}
? 进阶提示：若需频繁访问多级父级字段，建议封装为结构体而非 map，增强类型安全与 IDE 支持：
type UsersPageData struct {
Lang string
Users []User
}
tmpl.Execute(w, UsersPageData{Lang: "en", Users: users})
此时模板中 {{$.Lang}} 和 {{.Username}} 语义更清晰，且编译期即可捕获字段名错误。
总结：$ 是 Go 模板中跨越作用域访问根数据的“锚点”，掌握它，就能优雅处理任意深度的嵌套渲染场景。
