动态生成属性和脚本片段为何会被替换为安全占位符

Go 的 html/template 把模板作者当作可信方，把 Execute 接收的数据当作不可信方。动态值进入 href、事件属性或 后，模板引擎会先判断所在上下文，再选择 HTML、URL 或 JavaScript 转义；如果值会改变页面结构或协议安全边界，就可能被转成 #ZgotmplZ，或者只以普通文本形式出现。

这不是“模板丢数据”，也不是把字符串再拼一次就能修好的故障。正确做法是先定位上下文，再把动态行为改成白名单数据。只有完全受信任、已经在代码边界外完成审查的固定片段，才考虑使用带类型的安全内容。

官方地址：https://pkg.go.dev/html/template

先看值落在什么上下文里

同一个字符串放在文本节点、属性值和 JavaScript 中，风险完全不同。例如普通文本只需要处理 HTML 特殊字符，href 还要判断协议，脚本上下文则要避免字符串突破引号和代码边界。html/template 会在解析模板时为动作加入对应的上下文转义器，并不是执行时盲目调用一个通用的 Escape 函数。

你遇到的动态生成属性和脚本片段被自动替换为安全占位符，本质是Go的标准库html/template包内置的内容自动转义防护机制，这套机制会根据内容所处的HTML上下文位置，自动判断对应内容的安全等级，自动替换可能引发XSS注入的高风险字符，避免输出的页面出现安全漏洞。

排查时先把模板中的动作标出来：

package main

import (
	"bytes"
	"fmt"
	"html/template"
)

func main() {
	// 同一个字段分别进入链接属性和脚本字符串，观察上下文带来的差异。
	const page = `打开
`

	tpl, err := template.New("page").Parse(page)
	if err != nil {
		panic(err) // 模板语法或上下文不完整时，先修复 Parse 错误。
	}

	data := struct {
		Href  string
		Label string
	}{
		Href:  "javascript:alert('x')", // 不允许的协议会触发保护性处理。
		Label: ``,
	}

	var out bytes.Buffer
	if err := tpl.Execute(&out, data); err != nil {
		panic(err) // Execute 错误不能被忽略，否则无法区分空值和失败。
	}
	fmt.Println(out.String())
}

在链接上下文里，类似 javascript: 这样的协议不是普通文本，常见结果是 href="#ZgotmplZ"。脚本上下文则通常把字符串当作数据进行 JavaScript 转义；它不会因为字符串看起来像代码，就替你执行这段代码。这里要注意：不是所有动态脚本值都会变成同一个占位符，最终结果取决于动作所在的上下文和数据内容。

把“动态代码”改成“动态数据”

最稳妥的修复是让模板只表达固定结构，把变化部分收敛为枚举、ID、允许的 URL 或 JSON 数据。比如按钮需要执行三种动作，就传入 save、preview、cancel，由固定的前端函数根据枚举分支；不要把 onclick 的完整脚本拼进 Go 字符串。

type ViewData struct {
	// Action 是有限集合中的业务动作，不是可执行的 JavaScript 片段。
	Action string
	// ReturnURL 只保存业务需要的地址，渲染前还要通过协议白名单。
	ReturnURL string
}

func normalizeAction(action string) string {
	// 未知动作回落到安全分支，避免把外部输入变成代码。
	switch action {
	case "save", "preview", "cancel":
		return action
	default:
		return "preview"
	}
}

模板可以保留固定的 data-action 属性，或者把结构化数据编码到一个专用容器里，再由页面中已写死的事件处理器读取。动态链接也应当在 Go 侧先限制为 https、http 或站内相对路径，并拒绝控制字符、脚本协议和不需要的跳转形式。这样既能保留业务变化，也不会让用户输入拥有改变 HTML 结构的能力。

可信类型只能放在明确的边界上

html/template 提供 template.HTML、template.JS、template.URL 等类型，用来表示调用方已经确认过的特定上下文内容。它们不是“强制输出原字符串”的万能开关：一旦把请求参数、数据库富文本或第三方接口返回值直接转换成这些类型，自动转义就被越过，安全责任也从模板包转移到了你的代码。

工程上可以把可信内容构造封装在很小的函数里：输入先经过固定白名单和业务校验，函数返回专用类型，调用点旁边写明来源和允许范围。对用户可编辑内容，优先采用 Markdown/HTML 白名单清洗器或纯文本渲染，而不是直接转换成 template.HTML。对脚本配置，优先输出 JSON 数据；即使 JSON 中包含引号、换行或尖括号，也应让模板在 JavaScript 数据上下文中负责编码。

发布前用这份清单反向检查

1. 把出现占位符或转义的字段标成文本、HTML 属性、URL、CSS 还是 JavaScript 上下文。
2. 确认动态输入只描述数据，不包含标签、事件处理器和可执行语句。
3. 对链接检查协议白名单；对动作检查枚举；对 JSON 检查序列化边界。
4. 保留 Parse 与 Execute 的错误处理，不用忽略错误的方式“恢复显示”。
5. 只有真正可信的固定内容才能进入安全类型，并记录是谁构造、经过什么校验。

一句话判断：#ZgotmplZ 不是应该被清除的异常字符串，而是模板引擎告诉你“这个值正在尝试穿越不该穿越的上下文边界”。把代码还原为模板静态结构，把变化留给受约束的数据，通常比关闭保护更可靠。

常见问题

#ZgotmplZ 是不是 Go 模板损坏了？

通常不是。它表示值在当前上下文中不安全，尤其常见于 URL 协议不被允许的情况。先检查输入和属性上下文，不要直接替换占位符。

把 text/template 换掉就能保留脚本片段吗？

换成 text/template 只会失去 HTML 上下文保护，不能算修复。HTML 页面应继续使用 html/template，并改成数据驱动的行为。

什么时候可以使用 template.HTML？

仅在内容来源可信、结构经过明确审查且调用边界很小的时候使用。用户输入、数据库原文和外部响应都不应因为“看起来像 HTML”就直接转换。

为什么脚本变量能输出，但事件属性不执行？

脚本变量可能只是一个被安全编码的字符串，而事件属性期待的是另一种 JavaScript 上下文。把行为放进固定函数，把模板只用于传递数据，可以消除这类歧义。