Go html/template 自动转义 URL 时为什么改变了属性值

我第一次把查询链接放进 Go 模板时，看到源码里的 & 变成了 &，直觉是 URL 被改坏了。实际要先分清两层：服务端输出的是 HTML 源码，浏览器解析后才得到 href 属性值。对 href="{{.Link}}" 来说，html/template 会按 URL 上下文过滤、规范化，再按属性规则转义；因此源码出现 & 或 #，不等于用户点击时拿到同样的字面量。

最常见的 & 变成 & 是 HTML 属性源码的安全表示，浏览器解析后仍是查询串里的 &。真正需要警惕的是协议被过滤成 #ZgotmplZ，它说明输入不适合直接作为动态链接。

先用一个最小页面复现 URL 被改写

把问题缩成一个 URL 回显页，最容易看出改写发生在哪一层。这里故意传入一个包含两个查询参数的普通字符串，不把它包装成“安全 HTML”。

package main

import (
    "html/template"
    "log"
    "os"
)

const page = `{{.Label}}`

type viewData struct {
    Link  string
    Label string
}

func main() {
    // 普通字符串交给 html/template，让模板根据 href 上下文决定处理方式。
    data := viewData{
        Link:  "https://example.com/search?q=go&lang=zh",
        Label: "搜索 Go",
    }

    // Parse 会分析属性上下文；解析或执行失败都直接返回，避免输出半截页面。
    tmpl, err := template.New("page").Parse(page)
    if err != nil {
        log.Fatal(err)
    }
    // Execute 写出 HTML 源码，浏览器后续还会再解析其中的实体。
    if err := tmpl.Execute(os.Stdout, data); err != nil {
        log.Fatal(err)
    }
}

示例的 HTML 源码可能呈现为下面这样：

搜索 Go

这里的第二个 amp; 只是源码层的实体写法。浏览器把属性解析后，链接地址仍然是 https://example.com/search?q=go&lang=zh。如果你在服务端日志里比较字符串、在浏览器开发者工具里看 DOM 属性，看到的结果可能不同，不能只凭页面源代码判断链接是否失效。

为什么查询参数会出现 &

HTML 属性里，& 既可能是普通字符，也可能开启一个字符实体。模板不能把不可信数据原样塞进属性边界，所以会用实体形式表达特殊字符。对浏览器来说，& 会还原成一个 &；对你直接 curl 看到的响应文本来说，它仍是四个字符组成的源码。

这也是我排查此类问题时最先做的对照：同时记录响应体源码和浏览器最终属性值。若只是 &、引号、尖括号变成 HTML 实体，通常是上下文转义在工作；如果查询参数真的多了一层字面量 amp;，才要继续检查是否在模板之前已经手动调用了 url.QueryEscape、重复拼接，或把已经编码的值再次编码。

URL 前段和查询串不是同一种上下文

html/template 不只做字符替换，它会识别动态值所在的 URL 位置。链接的协议、主机和路径前段需要先经过 URL 过滤与规范化；查询串或片段中的保留字符，又要遵守 URL 编码和 HTML 属性编码的组合规则。

例如把用户输入直接放进 href，输入 javascript:alert(1) 时，模板可能用 #ZgotmplZ 替代它。这不是 URL 被“随机修改”，而是默认拒绝高风险协议。相反，https://example.com/a?q=go&lang=zh 的协议是常规 Web 协议，& 的实体化主要服务于 HTML 源码边界。

还有一个容易忽略的坑：不要把协议、路径、查询串拆成多个动态片段再拼接，例如 href="{{.Scheme}}:{{.Body}}"。模板只能看到局部值时，无法像看到完整 URL 那样判断整个链接的安全边界。工程上更稳妥的做法是后端先构造完整 URL，并把协议白名单、站内路径或允许的主机限制在业务代码里。

什么时候可以使用 template.URL

template.URL 表示调用者已经确认这段内容是安全 URL 或 URL 片段。它不是“关闭转义的显示开关”，而是把信任责任从模板转移给了业务代码。官方文档明确提醒，受信类型会让内容更接近原样进入输出，因此来源不明的数据库字段、请求参数和用户可编辑配置都不适合直接转换。

我的判断顺序通常是：第一，能否只允许站内相对路径；第二，是否可以用 net/url 解析后重新设置查询参数；第三，是否仍需要保留一段来自可信配置的完整 URL。只有第三种情况成立，才考虑受信 URL 类型，并把信任来源写在代码注释和调用边界旁边。为了让页面源码“看起来没变”而使用它，往往是在掩盖真正的输入问题。

一张验收清单，避免把转义当成故障

1. 先保存服务端响应体，再在浏览器中读取最终的 href 属性。
2. 确认 & 是否只存在于源码层；不要先做字符串替换。
3. 把协议、路径和查询串作为完整 URL 检查，避免分段动态拼接。
4. 对外部输入只允许业务需要的协议、主机和路径；遇到 #ZgotmplZ 就回到输入来源排查。
5. 只有确实来自可信配置的 URL 才讨论 template.URL，并接受它带来的安全责任。

相关问题

为什么 curl 看到的 URL 和浏览器地址不一样？

curl 展示的是 HTTP 响应源码，浏览器会继续解析 HTML 实体并形成 DOM 属性。比较时要明确自己比较的是响应文本还是解析后的属性。

把 href 改成 text/template 能解决吗？

不应该。text/template 不提供 HTML 上下文安全转义，换包可能让特殊字符突破属性边界；页面 HTML 应继续使用 html/template。

如何避免重复编码查询参数？

让 URL 只在一个明确边界编码一次：参数值交给 url.Values 或 url.URL 组装，再把完整结果传给模板，不要同时手写百分号编码和 HTML 实体替换。

官方资料：https://pkg.go.dev/html/template；实现细节可对照 https://github.com/golang/go/blob/master/src/html/template/escape.go。理解“源码层”和“浏览器解析层”的差异后，看到属性值变化时就能先判断它属于正常保护，还是业务代码的重复编码。