Go html/template 怎样识别自动转义后的 URL 类型

如果你在 html/template 的 href 中传入普通 string，模板不会把它当成“已经是 URL 的字符串”直接输出，而是先按 URL 上下文做自动转义；遇到不允许的动态协议，还可能输出 #ZgotmplZ。因此，识别 URL 类型的关键不是对最终 HTML 再做类型断言，而是看数据值的 Go 类型、模板所在上下文，以及是否经过了可信边界。

普通字符串为什么会变成 URL 上下文

html/template 会在解析模板时观察动作所在的位置。放在普通文本节点时，值主要按 HTML 文本处理；放在 href、src 等属性中时，模板会附加面向 URL 的转义和协议过滤。也就是说，自动转义后的“URL 类型”不是一个可以从渲染结果中取回的 Go 类型，而是模板上下文选择出的处理路径。

package main

import (
	"os"
	"text/template"
)

func main() {
	// 这里只展示上下文差异；真实 HTML 输出应使用 html/template 包。
	tpl := template.Must(template.New("demo").Parse(`文本：{{.}}
链接：打开`))
	_ = tpl.Execute(os.Stdout, "docs?a=hello world") // 普通 string 会按所在位置处理
}

上面的示例为了突出模板动作使用了 text/template，实际生成 HTML 时应把导入改成 html/template。在后者中，href 里的空格、引号、尖括号等字符不会沿用文本节点的处理方式。官方文档把这种行为称为上下文自动转义：模板作者负责结构，Execute 传入的数据默认按不可信文本处理。

怎样区分 string 与 template.URL

真正需要区分的是输入数据的 Go 类型。普通 string 表示未声明为安全的文本；template.URL 表示调用方已经确认这段内容是安全的 URL 或 URL 片段。后者不是“模板自动推断出来的 URL 类型”，而是开发者主动给出的信任声明。

package main

import (
	"html/template"
	"os"
)

type PageData struct {
	// Label 仍按普通文本处理，不能因为它和链接放在同一个结构体里就放宽规则。
	Label string
	// Href 只有在上游已经完成协议和路径校验后，才允许使用 template.URL。
	Href template.URL
}

func main() {
	const page = `{{.Label}}`
	t := template.Must(template.New("page").Parse(page))
	data := PageData{
		Label: "Go 文档",
		Href:  template.URL("/docs?lang=go"), // 受信任 URL 片段；不要直接接收用户输入
	}
	if err := t.Execute(os.Stdout, data); err != nil {
		// 执行失败时保留错误，不把半截 HTML 当成完整页面继续发送。
		panic(err)
	}
}

安全边界在于“谁可以构造 template.URL”。固定的站内路径、经过严格协议白名单和路径校验的配置值，才可能适合转换；表单字段、查询参数、第三方接口返回值不能因为看起来像 URL 就直接转换。官方源码明确提醒，URL 类型的内容会原样参与模板输出，使用它本身带来安全风险。

用 #ZgotmplZ 识别危险协议过滤

如果普通字符串放入 href 后变成 #ZgotmplZ，通常说明它没有通过该上下文允许的协议检查。比如 javascript: 是常见的动态脚本协议，html/template 默认会把它当成注入风险过滤掉。这个占位值是安全保护的结果，不应通过替换字符串或强制转换来“修复”。

package main

import (
	"html/template"
	"strings"
)

func safeSiteURL(raw string) (template.URL, bool) {
	// 只允许明确的站内路径；外部 URL 应单独做协议、主机和路径策略。
	if strings.HasPrefix(raw, "/") && !strings.HasPrefix(raw, "//") {
		return template.URL(raw), true // 这里的转换建立在本函数的白名单约束之后
	}
	return "", false // 拒绝 javascript:、协议相对地址和其它未审核输入
}

这个函数只适合演示“先校验、后建立信任类型”的边界，实际应用还要根据是否允许查询参数、反斜杠、编码后的控制字符和外部域名制定策略。若没有明确的白名单，继续传普通 string 让模板完成上下文转义，通常比手动构造 template.URL 更安全。

一张清单确认你识别的是类型边界

1. 先看动作位置：是在文本节点、href、src，还是 JavaScript/CSS 上下文。
2. 再看 Go 输入类型：普通 string 与 template.URL 的安全责任不同。
3. 检查结果是否出现 #ZgotmplZ；出现它时优先修正输入策略，不要改写输出占位符。
4. 如果必须使用 template.URL，把协议、主机和路径校验放在转换之前，并让转换函数成为唯一入口。
5. 不要把渲染后的 HTML 当作带类型对象；Execute 输出的是字节流，类型信息已经不再以 Go 值的形式保留。

常见问题

能不能从 Execute 之后的 HTML 反推出原始值是 template.URL 还是 string？

不能可靠反推。输出只保留最终文本，类型和模板上下文的处理已经完成；应在进入模板前记录或约束数据类型。

把 url.URL 转成 template.URL 就一定安全吗？

不一定。类型转换不会替你判断协议、主机、重定向和业务授权；只有完成应用层白名单校验后，才应建立受信任类型。