Go html/template 中 URL 参数为什么会被转义

在 Go 的 html/template 里，URL 参数出现 %20、%26 或加号，通常不是参数丢失，而是模板根据插入上下文做了 URL 转义。?q={{.}} 是查询值，/{{.}} 是路径片段，href="{{.}}" 还要检查整个链接的协议；三者的安全边界不同，不能用字符串替换强行“还原”。

先看变量放在 URL 的哪里：查询参数要让 html/template 负责编码，路径片段要按路径语义设计，完整链接必须限制协议。只要浏览器收到的链接仍能按预期解析，就不要把百分号编码当成错误。

同一个字符串放进 href，为什么会得到不同结果

html/template 会在解析模板时判断动作所在的上下文，并为动作补上内部转义阶段。普通文本主要处理 HTML 字符；进入 URI 后，还要避免值改变查询分隔符、属性边界或协议。

例如值是 Go & Web 时，查询参数中的空格和连接符会被编码，这是为了让它仍然是一个参数值，而不是把 & 误当成下一个参数的开始。路径片段也会编码，但它服务的是路径分段，不等价于查询字符串。

查询参数要让模板保留值的边界

搜索页最稳妥的模板通常把固定的查询键写在模板里，只把用户输入放进值的位置。这样读者看到的百分号编码就是参数值的一部分，服务端解析查询字符串时仍能得到原始语义。

package main

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

func main() {
    // 查询键由模板作者控制，用户输入只进入 q 的值位置。
    const page = `搜索`
    tmpl, err := template.New("search").Parse(page)
    if err != nil {
        log.Fatal(err) // 解析失败时不要继续输出未确认的模板。
    }

    // 空格和 & 会被编码，但不会改写 href 的查询参数边界。
    if err := tmpl.Execute(os.Stdout, `Go & Web`); err != nil {
        log.Fatal(err) // 输出失败也要让调用方知道响应不完整。
    }
}

这里的输入字符串故意包含 &，用来观察“一个值”是否被错误拆成多个参数。不要先调用 url.QueryEscape 再把结果交给查询上下文，否则容易形成重复编码；模板已经知道当前位置需要 URI 转义。

完整 href 变成 #ZgotmplZ 时先查协议

完整链接和查询值不是一回事。若模板是 ，传入 https://example.com/ 这类允许协议通常可以正常表达；传入带有不安全协议的值时，html/template 会用 #ZgotmplZ 代替它，避免数据值获得执行或导航能力。

因此，#ZgotmplZ 不是“URL 编码太多”的提示，而是模板安全模型拒绝了当前 URL。修复顺序应是：先确认变量究竟是完整链接还是相对路径，再在业务层允许明确的协议集合；不要为了让文本原样出现，就把不可信字符串转换成 template.URL。

用四项检查把模板修正到正确上下文

1. 先标记数据类型。问清变量是搜索词、路径片段还是完整 URL，避免所有字符串都走同一个拼接函数。
2. 固定结构，变量只占值位。把 ?q=、属性引号和路径分隔符写在模板中，减少用户输入影响 HTML 结构的机会。
3. 观察解析后的语义。浏览器或服务端解析后，确认空格仍属于值、& 没有意外新增参数，危险协议没有被放行。
4. 谨慎使用安全类型。template.URL、template.HTML 等类型表达“调用方已承担信任责任”，不能拿来消除陌生输入的转义。

如果业务确实要支持外部链接，可以在生成模板数据前做协议白名单和业务校验；如果只是搜索或筛选，优先使用固定路径加查询参数的写法。这样既保留自动转义，也让代码审查者能直接看出数据边界。

常见问题

URL 参数里的 %20 是不是编码错误？

通常不是。它表示空格等字符被编码为查询值的一部分，重点是检查最终 URL 的解析结果，而不是要求 HTML 源码看起来像输入字符串。

为什么不能把 html/template 换成 text/template？

输出目标是 HTML 时，html/template 才会按 HTML、URI、JavaScript 等上下文保护结构；换包会丢失这层安全语义。

template.URL 能不能解决所有转义问题？

不能。它只适合已经由可信代码构造并确认安全的 URL 值。对用户输入直接套安全类型，会把本应保留的防护责任转嫁给模板调用方。

排查这类现象时，先把“编码结果”和“安全拒绝”分开：前者说明模板在保护参数边界，后者说明完整链接的协议或上下文不符合安全模型。沿着数据真正所在的位置修正，通常比手工替换百分号更可靠。