Go Template是Go语言标准库提供的内置模板引擎，在Web开发、配置文件生成等场景中应用广泛。当我们在模板中使用range循环遍历集合时，经常会需要同时获取循环外部的父级变量或者全局配置变量，但受作用域限制，直接访问往往会出现变量未定义的错误。
Go Template的作用域规则
Go Template的作用域分为全局作用域和局部作用域，全局作用域中定义的变量可以在模板的任何位置访问，而range、with等语句会创建新的局部作用域，局部作用域内默认只能访问当前作用域的变量和当前迭代的元素。当我们在局部作用域中访问一个变量时，模板引擎会先从当前局部作用域查找，找不到才会向上查找父级作用域，直到全局作用域。
普通变量的作用域表现
我们先看一个基础的模板示例，演示普通变量的作用域问题：
package main
import (
"os"
"text/template"
)
func main() {
// 定义模板内容
tpl := `全局变量: {{.GlobalVar}}
{{range .List}}
当前循环元素: {{.}}
尝试访问全局变量: {{.GlobalVar}}
{{end}}`
// 准备模板数据
data := map[string]interface{}{
"GlobalVar": "我是全局变量",
"List": []string{"元素1", "元素2", "元素3"},
}
// 解析并执行模板
t, _ := template.New("test").Parse(tpl)
t.Execute(os.Stdout, data)
}
执行上述代码后，会发现循环内部访问.GlobalVar时输出为空，这是因为range循环的局部作用域中，.被重新赋值为当前迭代的元素，所以无法直接通过.访问到外部的全局变量。
访问父级上下文变量的方法
通过$符号引用全局变量
Go Template中，$符号代表模板的全局根上下文，也就是传递给模板执行函数的顶层数据。我们可以在循环外部将需要的父级变量赋值给以$开头的变量，然后在循环内部通过该变量访问。
修改后的模板代码如下：
package main
import (
"os"
"text/template"
)
func main() {
// 定义模板内容，使用$定义全局可访问的变量
tpl := `{{$globalVar := .GlobalVar}}
全局变量: {{$globalVar}}
{{range .List}}
当前循环元素: {{.}}
通过$访问全局变量: {{$globalVar}}
{{end}}`
// 准备模板数据
data := map[string]interface{}{
"GlobalVar": "我是全局变量",
"List": []string{"元素1", "元素2", "元素3"},
}
// 解析并执行模板
t, _ := template.New("test").Parse(tpl)
t.Execute(os.Stdout, data)
}
执行后可以看到，循环内部成功输出了全局变量的值，这是因为$globalVar是定义在全局作用域的变量，不受range局部作用域的影响。
访问父级作用域的局部变量
如果我们需要访问的是range外层定义的局部变量，而不是顶层数据，同样可以通过$来传递。比如外层先定义一个局部变量，再在循环中使用：
package main
import (
"os"
"text/template"
)
func main() {
// 定义模板内容，外层定义局部变量
tpl := `{{$parentVar := "我是父级局部变量"}}
父级变量: {{$parentVar}}
{{range .List}}
当前循环元素: {{.}}
访问父级局部变量: {{$parentVar}}
{{end}}`
// 准备模板数据
data := map[string]interface{}{
"List": []string{"元素1", "元素2", "元素3"},
}
// 解析并执行模板
t, _ := template.New("test").Parse(tpl)
t.Execute(os.Stdout, data)
}
访问全局上下文变量的注意事项
如果全局变量是嵌套在顶层数据中的对象，我们可以直接通过$.嵌套字段名的方式访问，不需要额外定义变量。比如顶层数据有一个Config字段，里面包含全局配置：
package main
import (
"os"
"text/template"
)
func main() {
// 定义模板内容，直接通过$访问嵌套的全局配置
tpl := `{{range .List}}
当前循环元素: {{.}}
全局配置站点名: {{$.Config.SiteName}}
全局配置版本号: {{$.Config.Version}}
{{end}}`
// 准备模板数据
data := map[string]interface{}{
"List": []string{"元素1", "元素2", "元素3"},
"Config": map[string]interface{}{
"SiteName": "测试站点",
"Version": "1.0.0",
},
}
// 解析并执行模板
t, _ := template.New("test").Parse(tpl)
t.Execute(os.Stdout, data)
}
这种方式适合直接访问顶层数据的嵌套字段，不需要提前定义变量，代码更简洁。
常见问题总结
- range循环内部
.会被重新赋值为当前迭代元素，不要直接用.访问外部变量 - 以
$开头的变量是全局作用域变量，在任意位置都可以访问 - 如果顶层数据有嵌套结构，可以通过
$.字段名直接访问，无需额外定义变量 - with语句和range语句一样会创建新的局部作用域，访问外部变量的方法和range一致
掌握Go Template的作用域规则和变量访问方法，就可以轻松解决range循环内访问父级或全局变量的问题，避免开发中出现不必要的错误。
Go_Templaterange循环父级上下文变量全局上下文变量修改时间：2026-07-06 20:12:30