Go html/template CSS 类型值的安全传入与信任边界

在 Go 的 html/template 中，style="{{.Style}}" 属于 CSS 上下文。普通字符串会经过上下文转义；只有当样式内容来自可审计的白名单、固定主题配置或可信生成器时，才适合转换成 template.CSS。这个类型表示“调用方已经确认内容是安全 CSS”，不是给用户输入加上的通行证。

官方参考：https://pkg.go.dev/html/template#CSS

CSS 上下文和普通字符串不是一回事

html/template 会根据动作所在位置选择转义方式。放在 HTML 文本里的字符串、放在 URL 属性里的字符串，以及放在 CSS 或 JavaScript 上下文里的字符串，边界都不同。官方文档明确说明它支持 CSS 上下文；因此把所有值都当作“字符串转义完就安全”并不可靠。

例如下面的模板只想接收一个受控的颜色声明：

const page = `
内容
`

// Style 是 CSS 上下文中的值，不能把请求参数直接塞进来。
type ViewData struct {
	Style template.CSS
}

// 只把有限的主题名映射为固定 CSS，未知值回退到默认样式。
func styleForTheme(theme string) template.CSS {
	switch theme {
	case "ocean":
		return template.CSS("color: #145da0; background-color: #eaf5ff")
	case "forest":
		return template.CSS("color: #1f6338; background-color: #eef9f0")
	default:
		return template.CSS("color: #263238; background-color: #ffffff")
	}
}

用白名单建立 template.CSS 的可信入口

安全入口应先处理“允许哪些主题”，再处理“如何渲染”。主题名可以来自 URL 或表单，但它只能作为查表键；最终返回的 CSS 必须来自代码中的有限集合。不要用 template.CSS(userInput) 代替校验，也不要因为输出位置是 style 就把来自数据库的任意字符串标记为安全。

模板解析和执行仍要检查错误。下面的写法保留了错误返回，便于把模板语法错误和数据边界问题分开定位：

func render(w io.Writer, theme string) error {
	// Parse 阶段检查模板是否能被正确解析，不能把错误吞掉。
	tmpl, err := template.New("card").Parse(page)
	if err != nil {
		return fmt.Errorf("parse card template: %w", err)
	}

	// Execute 阶段只接收已经由白名单函数构造出的 CSS 类型值。
	data := ViewData{Style: styleForTheme(theme)}
	if err := tmpl.Execute(w, data); err != nil {
		return fmt.Errorf("execute card template: %w", err)
	}
	return nil
}

如果这里出现 ZgotmplZ，不要简单改成 template.HTML 或关闭安全处理。先检查模板动作处于哪个上下文，再确认传入值是否来自允许的 CSS 生成路径。错误提示的价值正在于提醒你：当前值不能安全地进入该位置。

安全类型的适用范围与拒绝清单

生产代码里可以把 CSS 类型封装在主题配置层，让 HTTP handler 只传递主题名或枚举值。这样一来，模板层不需要理解数据库字段的来源，配置层也能集中做颜色、单位、分号和允许属性的检查。对于复杂样式，优先改成固定 class 名并在静态 CSS 中维护规则，动态 style 只保留确有必要的少量值。

常见问题

template.CSS 能不能包住用户输入的颜色？

不建议直接包住。将用户输入解析为颜色并限制格式、属性和值之后，可以把“验证后的结果”作为 CSS；更稳妥的做法是把颜色映射到固定主题或固定 class。

为什么普通字符串在 style 属性里可能得到异常输出？

因为模板会按 CSS 上下文处理动态值，安全判断不只看字符串本身。异常值可能被拒绝或替换，排查时要同时看模板位置和来源，而不是只改转义函数。

可以用 template.HTML 解决 CSS 输出问题吗？

不可以。template.HTML 表示可信 HTML 片段，和 CSS 上下文不是同一套语义。跨上下文强行转换会扩大信任范围，应该回到具体类型和允许值设计。