Go html/template 怎样避免 URL 上下文误用

我第一次把站内跳转地址放进 Go 模板时，犯的错不是忘记转义，而是把“普通字符串”和“已经确认安全的完整 URL”混成了一种数据。结果是：同一个变量放在正文里可以正常显示，放进 href 后却被改写成了看起来奇怪的值。这个现象通常不是 html/template 失效，而是它正在按 URL 上下文保护页面。

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

html/template 的正确用法是让模板保留真实的 HTML、属性和 URL 结构，把外部数据作为普通值传入；只有来自可信配置、且已经确认安全的完整地址，才考虑使用 template.URL。不要为了让链接“看起来能用”而把用户输入强行转换成安全类型。

先看清：同一个值换个位置就换了上下文

html/template 和 text/template 的最大区别之一，是前者会根据动作所在的位置加入上下文处理。普通文本需要防止标签边界被数据打破；href、src 等属性还要额外考虑 URL 的协议和属性边界。

因此，下面两处插值虽然写法相似，含义并不相同：第一处只是展示文字，第二处会被当作 URL 的一部分分析。图 1 是结构说明图，重点看“模板位置”如何决定后面的处理边界，不是浏览器运行截图。

const page = `
{{.Label}}
打开页面
搜索
`

// html/template 会根据每个动作所在的上下文选择处理方式。
tmpl, err := template.New("page").Parse(page)
if err != nil {
    // 模板结构不完整时，应保留解析错误，不要靠替换字符串掩盖它。
    return err
}

这里的关键不是手工记住内部的转义函数名称，而是把结构交给模板作者，把数据留在动作位置。尤其不要先把 拼成字符串，再让模板把整段字符串当作 HTML 输出。

完整链接和查询参数，分别采用什么写法

我在项目里通常把 URL 分成两类处理：固定的路径结构由模板写死，变化的值作为普通字符串传入；如果整个地址来自配置，则在进入模板前完成来源确认。这样既能让模板知道当前上下文，也不需要在业务代码里手工调用一串 HTML 转义函数。

type PageData struct {
    // Query 只是搜索词，不代表一整段 URL。
    Query string
    // Link 来自应用生成的站内地址，仍作为普通 string 交给模板。
    Link string
}

const page = `

  搜索

查看详情
`

// 让 html/template 按属性、查询参数和文本位置分别处理数据。
tmpl, err := template.New("page").Parse(page)
if err != nil {
    return err
}

如果你需要拼接查询参数，优先让模板保留 /search?q= 这样的固定结构，而不是把 ?、& 和用户值在业务层拼成一段 HTML。对于更复杂的 URL，可以在 Go 代码里使用 net/url 组装地址，再把最终结果作为普通字符串传入；模板仍然负责它所在的 HTML 属性上下文。

这里有一个容易误会的点：自动转义解决的是输出上下文，不会替你判断业务上这个地址是否应该允许访问，也不会替你校验站内跳转规则。协议白名单、允许的主机和路径范围，仍然应该在业务代码中明确制定。

为什么出现 #ZgotmplZ，template.URL 又该不该用

当普通字符串进入 URL 上下文，而值带有不安全协议或无法被安全解释时，html/template 可能把它过滤成 #ZgotmplZ。这不是应该通过替换字符串绕开的“乱码”，而是告诉你：模板收到的值不能直接作为资源或跳转地址使用。

template.URL 是一个带信任含义的类型。它适合由应用自己的固定配置、经过严格审核的资源地址或可信的 URL 生成器提供的值；它不适合包住表单字段、请求参数、数据库中未经确认的内容。图 2 把普通字符串和安全类型的边界分开画出，关系线只表示数据边界，不表示运行时步骤。

type PageData struct {
    UserLink string
    DocsLink template.URL
}

// UserLink 可能来自请求参数，保持普通 string 才能继续接受上下文保护。
data := PageData{
    UserLink: request.URL.Query().Get("next"),
    // DocsLink 只来自应用固定配置，不把用户输入转换成 template.URL。
    DocsLink: template.URL("https://go.dev/doc/"),
}

// 模板中仍然使用 href 属性，让 html/template 处理属性边界。
const page = `返回文档`

如果 DocsLink 也会被用户控制，就应该把字段改回 string，并在业务层先验证协议、主机和路径，再决定是否生成页面。类型转换本身不是验证，它只是向模板声明“这个值已经被信任”，声明错了反而扩大风险。

按三个边界排查 URL 上下文问题

我最后保留了一条简单的选择规则：普通用户数据始终用 string；固定路径和查询结构写在模板里；可信完整 URL 才考虑 template.URL；一旦说不清来源，就不要使用安全类型。

常见问题

使用 html/template 后还需要手工调用 HTMLEscapeString 吗？

通常不需要。模板包会依据动作所在的上下文加入处理逻辑，重复手工转义还可能让内容变成双重编码。先修正模板结构和数据边界，再处理确实发生在模板外的文本转换。

template.URL 能让任意链接都正常显示吗？

它表达的是可信 URL 类型，不是通用的“解过滤”开关。对用户输入或未经确认的数据库值使用它，会跳过本来应该存在的保护；不确定来源时保持普通字符串。

归根结底，html/template 的 URL 安全依赖两件事：模板要把数据放在明确的上下文中，业务代码要对“哪些地址可以被访问”做自己的约束。把这两层分开，#ZgotmplZ 就会从令人困惑的输出变成有用的排查线索。