用最小模板区分正常转义和真正异常

排查时保留三组输入：纯文本、带尖括号的文本、带查询参数的 URL。分别记录模板位置、期望的浏览器语义和实际输出。若文本节点只是显示了转义后的字面量，说明数据被当作普通文本处理；若链接失效，再检查是否把完整 URL 错放进了不合适的上下文，或在模板外又做了一次编码。

package main

import (
    "os"
    "html/template"
)

type PageData struct {
    Title string
    Link  string
}

func main() {
    // 让模板自己识别文本节点和 href 属性的上下文。
    const page = `
{{.Title}}
打开`
    tmpl := template.Must(template.New("page").Parse(page))
    data := PageData{
        // 尖括号会在标题文本中被当作数据，而不是标签。
        Title: `标题`,
        // URL 中的特殊字符会按属性和 URL 上下文处理。
        Link: `/search?q=go template`,
    }
    // Execute 可能写出部分结果，所以生产代码仍应检查返回错误。
    if err := tmpl.Execute(os.Stdout, data); err != nil {
        panic(err)
    }
}

如果页面“多出实体字符”，先检查浏览器是否把服务端输出再次当作普通文本插入，例如前端代码使用了 textContent 而不是预期的 HTML 插入方式；如果页面“少了标签”，则先确认这些标签本来是否来自用户输入。模板层的安全转义不应被当作富文本渲染器。

可信 HTML 类型不能拿来包裹用户输入

html/template 提供 template.HTML、template.URL 等内容类型，用于表达调用方已经确认安全的内容。它们不是“关闭自动转义”的通用开关。官方源码明确提醒，封装后的内容会以相应语义进入输出，错误地把第三方或用户输入转换成可信类型会重新引入注入风险。

package main

import (
    "html/template"
    "os"
)

type ViewData struct {
    // HTML 只能接收经过可信来源或可靠清洗器处理的片段。
    TrustedHTML template.HTML
    PlainText   string
}

func main() {
    tmpl := template.Must(template.New("view").Parse(`
{{.TrustedHTML}}
{{.PlainText}}
`))
    data := ViewData{
        // 这是固定在代码中的演示片段，不代表用户输入可以直接转换。
        TrustedHTML: template.HTML(`已确认的片段`),
        PlainText:   `必须按文字显示`,
    }
    // 输出后仍要检查错误，避免把部分结果当成完整页面。
    if err := tmpl.Execute(os.Stdout, data); err != nil {
        panic(err)
    }
}

如果需求只是让用户看到原始 HTML 字符，继续使用普通 string；如果需求是富文本，先做允许标签、属性和 URL 协议的清洗，再把清洗器的输出边界封装起来。不要因为页面显示“多了转义字符”就把所有数据都转换为 template.HTML。

最后检查 Parse 和 Execute 的生命周期

另一个容易被误认为“页面显示异常”的问题，是模板对象已经执行过，却又在同一对象上追加解析。html/template 在执行时会完成上下文转义；官方实现会记录已转义状态，执行后继续 Parse 会返回不能再解析的错误。模板应在初始化阶段完成 Parse，服务请求阶段只执行已经准备好的模板。

package main

import (
    "html/template"
    "os"
)

func main() {
    // 初始化阶段完成解析，避免请求处理时重复改写模板树。
    tmpl := template.Must(template.New("page").Parse(`
{{.}}
`))
    if err := tmpl.Execute(os.Stdout, "普通文本"); err != nil {
        panic(err)
    }
    // 不要在 Execute 之后继续 Parse；需要变体时应在初始化阶段 Clone。
}

常见问题

能不能换成 text/template 让标签直接生效？

不建议。HTML 页面应使用 html/template；换成 text/template 只是绕过上下文保护，不是修复显示问题。需要富文本时应先清洗，再明确传递可信类型。

为什么属性中的值和文本节点显示不一样？

因为转义依赖上下文。属性值需要保护引号和标签结构，URL 还会进行 URL 相关处理。先确认数据所在位置，再判断结果是否符合浏览器语义。

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

只有当片段来自可信代码或已经通过可靠清洗并且调用方明确承担安全责任时才考虑。用户输入、第三方内容和未经审查的 Markdown 转 HTML 都不能直接转换。

处理这类异常时，最稳妥的顺序是：先看上下文，再做最小复现；先保留普通字符串，再确认可信来源；最后把模板解析固定在初始化阶段。这样既能解释页面为什么“看起来变了”，也不会为了追求原样输出而丢掉自动转义的安全边界。