html/template 模板中如何安全输出 URL 属性

我在给 Go 模板增加“跳转到详情页”时，最先想做的事情通常是把 URL 当成普通字符串拼进 HTML。这个做法看起来直接，却把两个不同问题混在了一起：HTML 属性需要正确编码，URL 还需要判断协议是否允许。html/template 的正确用法是让动态值直接出现在属性上下文里，由模板引擎按位置处理；只有业务确实信任并允许的特殊 URL，才考虑额外的类型约束。

先记住一个可落地的结论：普通用户输入不要手工拼成 HTML，也不要直接转换成 template.URL。对于 href、src 这类属性，优先写成 href="{{.URL}}"，再在进入模板前对业务允许的协议做限制。

先分清 URL 属性和普通文本

同一个值放到 HTML 文本节点、普通属性和 URL 属性里，处理方式并不相同。文本节点主要需要 HTML 转义；title 这类属性要保护引号和标签边界；而 href、src 还要考虑 URL 的协议部分。html/template 会根据模板上下文插入对应的处理逻辑，这也是它和只处理文本的模板方式的关键区别。

因此模板最好保持结构清楚，属性值始终使用引号包住：

{{.Label}}

不要把用户输入先交给字符串格式化函数，再把整段结果作为 template.HTML 输出。那样会绕开模板原本能提供的上下文边界。

让 html/template 直接处理 URL 属性

我更愿意把“生成 HTML”和“决定链接是否可用”拆开。模板只负责把已经确定的数据放到正确位置，业务代码负责决定数据是否满足自己的链接规则。最小模板可以这样写：

package main

import (
	"bytes"
	"fmt"
	"html/template"
)

type Link struct {
	Label string
	URL   string
}

func main() {
	// 直接把 URL 放进 href，让模板识别 URL 属性上下文。
	t := template.Must(template.New("link").Parse(
		`{{.Label}}`,
	))
	links := []Link{
		{Label: "站内详情", URL: "/docs/42?from=list"},
		{Label: "外部文档", URL: "https://go.dev/"},
		{Label: "不允许的协议", URL: "javascript:alert(1)"},
	}

	for _, link := range links {
		var out bytes.Buffer
		// Execute 的错误要返回给调用方，不能静默丢掉模板输出。
		if err := t.Execute(&out, link); err != nil {
			fmt.Println("render error:", err)
			continue
		}
		fmt.Println(out.String())
	}
}

这里的重点不是记住某个转义字符串，而是保留上下文。相对 URL 和常见的 http、https、mailto 协议可以按模板规则处理；不安全协议进入 URL 上下文时，会被替换成模板的安全兜底值，而不是原样执行。

查询参数也不要把整条链接先拼好再转义。让查询值处在查询上下文里，模板会按 URL 查询部分处理：

搜索

业务允许自定义协议时怎么收紧边界

有些应用确实需要自定义协议，例如桌面客户端跳转或内部资源协议。这时不要因为一次需求就把所有输入都转为 template.URL。template.URL 表示调用方已经确认这段 URL 是可信内容，模板会减少默认过滤；它不是“把危险字符串变安全”的转换器。

更稳妥的做法是先解析，再只放行业务需要的协议。下面的函数故意只允许相对地址、http 和 https，如果以后要增加自定义协议，就把它作为明确的代码审查项加入允许列表：

package link

import (
	"fmt"
	"net/url"
	"strings"
)

func AllowedURL(raw string) (string, error) {
	parsed, err := url.Parse(strings.TrimSpace(raw))
	if err != nil {
		return "", fmt.Errorf("parse URL: %w", err)
	}

	// 空 scheme 表示相对地址；这里只允许业务明确需要的两种网络协议。
	switch strings.ToLower(parsed.Scheme) {
	case "", "http", "https":
		return parsed.String(), nil
	default:
		return "", fmt.Errorf("unsupported URL scheme %q", parsed.Scheme)
	}
}

调用方拿到 AllowedURL 的结果后，仍然以普通字符串交给 html/template 即可。只有数据来自真正可信、且已经经过明确边界控制的内部配置时，才有理由使用 template.URL；表单、数据库中的用户可编辑字段、第三方接口返回值都不应默认视为可信。

我会在评审里检查的几个细节

第一，属性是否有成对的引号。没有引号时，模板很难稳定判断属性边界，复杂条件下还可能出现上下文歧义。第二，是否重复使用 urlquery、html 等手工 escaper。通常应该先让 html/template 自己根据位置处理，重复转义容易得到不可用的链接。

第三，是否把 URL 的安全性和权限混为一谈。模板可以过滤危险协议，但它不替代登录校验、授权判断或跳转域名策略。第四，是否把失败状态做成可见的业务结果：链接被拒绝时，可以记录原因并渲染一个没有跳转行为的普通文本，而不是继续把原始值塞回 HTML。

常见问题

为什么 href 里出现了 #ZgotmplZ？

通常说明字符串带有模板认为不安全的协议，或者处在无法明确判断的 URL 上下文。先记录原始输入和解析出的 scheme，再决定是拒绝、改成站内相对地址，还是补充经过审查的业务允许列表。

可以先用 url.QueryEscape 再放进 href 吗？

不要把“查询值编码”和“整条 URL 放进属性”混为一谈。优先保持模板结构，让动态值出现在它真实的查询上下文中；只有独立构造 URL 的代码确实需要时，才在对应的 URL 解析和编码层处理。

template.URL 能不能解决所有 URL 安全问题？

不能。它表达的是“这段内容已经被信任”，不是验证器，也不会替你做权限、域名或业务跳转判断。对外部输入，普通字符串加明确的协议允许列表更容易审查。