在 Go 的 html/template 包中，模板引擎会根据标签上下文自动对变量进行转义，这在 HTML、JavaScript 和 URL 位置能挡住大量注入，但 CSS 上下文中的行为并不等同于安全过滤。不少开发者在做换肤或主题定制时，直接把颜色字符串放进<style>标签，结果要么合法样式被转义得面目全非，要么图省事改用 template.CSS 跳过转义，给页面留下 CSS 注入隐患。本文从上下文转义机制讲起，再讨论白名单校验和 Content-Security-Policy 加固，帮助你判断哪些 CSS 内容可以安全进入模板。
理解 html/template 在 style 块中的转义行为
html/template 解析模板时会根据当前上下文切换状态，而<style>元素内部属于 CSS 块上下文。当模板变量以字符串形式出现在这里时，模板包会应用 CSS 转义函数，把双引号、单引号、小于号、大于号、与号等字符改写成反斜杠加十六进制形式，例如 < 可能会变成 \3c。这种转义的设计目标是防止变量值跳出当前 CSS 位置并破坏 HTML 结构，但它并不会完整校验 CSS 语法。很多合法的颜色值不受影响，但带括号、分号或 url() 的内容容易被改写，从而导致页面样式静默失败。
可以看一个最小例子。模板内容如下：
<style>
body {
background: {{.BgColor}};
}
</style>
在 Go 代码里传入 .BgColor = "#f5a623"，执行后输出一般正常，因为 # 和十六进制字符被 CSS 上下文接受。但如果 .BgColor 是 "#f5a623; background-image: url(https://attacker.test)"，输出行为就不会像预期那样简单了——某些特殊字符会被转义，但分号、冒号、括号和 url 关键字往往被保留，导致攻击者仍可能追加新的样式声明。这里需要强调：自动转义不是在过滤恶意 CSS，它只是阻止变量逃逸到 HTML 或 JavaScript 上下文。
因此，如果你确实想让一段 CSS 原样输出，html/template 提供了 template.CSS 类型，它表示该值已经过安全处理，模板引擎不会再转义。下面的代码演示了基本用法：
type Theme struct {
Color template.CSS
}
t := template.Must(template.New("page").Parse(`
<style>
body { background: {{.Color}}; }
</style>
`))
t.Execute(os.Stdout, Theme{Color: template.CSS("#f5a623")})
这段代码能输出预期的内联样式，但前提是 Color 的值必须完全可信。任何直接包装用户输入的写法，比如 template.CSS(r.FormValue("color"))，都会让前面的转义保护失效。这就是“安全注入”和“粗暴跳过转义”的差别。
建立白名单校验，不要把用户输入直接变成 template.CSS
对于典型的自定义需求，颜色值是最常见的注入点。与其写一个复杂的正则去匹配所有可能的颜色表达，不如只放行你能明确接受的格式。比如仅允许三位或六位十六进制颜色，或者 rgb/rgba 的整数形式。这样做的好处是规则简单，误判率低，审计时也容易证明安全边界。任何不匹配的值都返回一个默认安全值，或者直接不输出该样式。
下面是一个只允许十六进制颜色的安全函数，它的返回值是 template.CSS，因此可以直接在模板中调用：
var hexColorRe = regexp.MustCompile(`^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$`)
func safeColor(value string) template.CSS {
if !hexColorRe.MatchString(value) {
return template.CSS("#ffffff")
}
return template.CSS(value)
}
t := template.New("page").Funcs(template.FuncMap{
"safeColor": safeColor,
})
t.Parse(`<style>body { background: {{safeColor .BgColor}}; }</style>`)
这个函数只接受 #fff 或 #f5a623 这样的值，否则回退到 #ffffff。由于返回值是 template.CSS，html/template 不会二次转义；正则已经保证它不可能包含分号、括号或 url 关键字。这跟 template.HTML 的受信任类型思路类似，关键点都在于内容必须经过你的校验逻辑，而不是直接来自不可信输入。
如果需要的可配置项更多，不建议把 padding、border、font-family 等自由文本都塞进内联样式。更好的设计是预设一组主题类名或 CSS 变量，由用户从服务端枚举中选择，而不是接收任意字符串。例如用户选择一个主题 ID，后端根据 ID 映射到一个已经写好的 CSS 文件或预设样式块。真要支持自定义颜色，可以只开放两三个颜色槽位，每个槽位都用与上面类似的独立校验。这种白名单加枚举的思路，比尝试过滤所有危险字符可靠得多。
用 Content-Security-Policy 与 nonce 加强内联样式安全
即便在服务端做了严格校验，仍然建议在响应头里设置 Content-Security-Policy，作为浏览器侧的防线。CSP 可以限制页面允许加载哪些样式资源，以及是否允许内联 <style> 标签。如果完全不使用内联样式，可以设置 style-src 'self'，这样所有内联 style 都会被禁用，攻击者即使注入标签也无法生效。但本文讨论的场景本身需要注入 CSS，因此需要在内联样式上使用 nonce。
nonce 是每次请求随机生成的一次性令牌，写到<style>标签的 nonce 属性中，同时出现在 CSP 响应头里。浏览器只允许 nonce 匹配的 style 标签执行。代码示例：
nonceBytes := make([]byte, 16)
if _, err := rand.Read(nonceBytes); err != nil {
panic(err)
}
nonce := base64.StdEncoding.EncodeToString(nonceBytes)
w.Header().Set("Content-Security-Policy", "style-src 'self' 'nonce-"+nonce+"'")
t.Execute(w, map[string]any{
"Nonce": nonce,
"BgColor": template.CSS("#f5a623"),
})
对应模板：
<style nonce="{{.Nonce}}">
body {
background: {{.BgColor}};
}
</style>
在 Go 里 {{.Nonce}} 会被属性上下文转义，这里只包含 base64 字符，所以不会产生额外问题。攻击者如果通过 CSS 注入插入新的<style>标签，会因为没有正确的 nonce 而被浏览器拒绝。
但要注意 CSP 不是万能药。style-src 主要管样式来源，不能彻底阻止通过 CSS 触发的图片请求；你还需要根据实际情况配置 img-src、font-src、connect-src 等指令。更重要的是，CSP 的 nonce 值不能被缓存复用，每次响应都应当重新生成。通常可以把校验逻辑放在中间件里统一处理，而不是在业务 handler 中散落。结合前面的模板层校验和这里的浏览器层限制，才能把动态 CSS 注入控制在可接受的风险范围内。
Go HTML模板CSS注入html/template修改时间：2026-09-29 06:28:47