urls

urls.PathEscape

返回给定字符串,并对特殊字符与保留分隔符做百分号编码,使其可以安全地用作 URL 路径中的一个片段。

签名
urls.PathEscape INPUT
返回类型
string

这一页解决什么问题

要把一段可能含空格、中文或 / 的文本放进 URL 的某一段路径里。如果不编码,空格会截断地址,/ 会被当成新的层级,中文在不同浏览器里表现也不一致。urls.PathEscape 对片段做百分号编码,保证它只会被当作一个整体。

什么时候用,什么时候别用

该用:

  • 把术语名、标签、文件名之类的值拼进一条路径的某一层;
  • 想得到编码后的片段再交给 urls.JoinPath 拼接。

别用:

  • 要编码整条 URL 或查询字符串 → 本函数不会编码 =、&(实测见下文),查询串请用 querify 或自行拼接;
  • 要生成 HTML 锚点 id → 用 urls.Anchorize;
  • 要生成 slug(空格变短横、标点丢弃)→ 用 urls.URLize;
  • 想解码 → 用 urls.PathUnescape。

用法

(0.153.0 新增)

urls.PathEscape 函数执行 urls.PathUnescape 的逆变换。

go-html-template
{{ urls.PathEscape "my café" }} → my%20caf%C3%A9

用该函数转义字符串,使其可以安全地用作 URL 路径中的单个片段。

完整示例(实测)

layouts/_partials/segment.htmlgo-html-template
[{{ urls.PathEscape "my café" }}]|[{{ urls.PathEscape "a/b?c=d&e" }}]

Hugo 0.167.0 实测输出(第二项的 & 在网页里会显示为 &,函数返回的原始值是 &):

[my%20caf%C3%A9]|[a%2Fb%3Fc=d&e]

你应当看到什么:空格变 %20,é 变 %C3%A9;第二项里 / 变 %2F、? 变 %3F,但 = 与 & 原样保留——所以它适合编码路径片段,不适合编码查询字符串。

返回值边界(实测)

测量条件:Hugo 0.167.0 extended,单语言站点(locale = 'zh-CN'),Windows。

输入 结果 是否报错
"my café" my%20caf%C3%A9(空格 → %20,非 ASCII → UTF-8 百分号编码) 否
"a/b?c=d&e" a%2Fb%3Fc=d&e(/、? 被编码;=、& 不被编码) 否
已经是纯 ASCII 字母数字 原样返回 否
返回类型 string 否

常见坑

类别 症状 真因 怎么修
没报错但结果不对 查询参数拼接后语义错乱 本函数不编码 =、&,它们会被解析成参数分隔符 查询串不要用 PathEscape,用 querify 或手工拼
没报错但结果不对 地址里出现 %20,但站点目录里是短横 PathEscape 做的是百分号编码,不会把空格换成短横 要 slug 语义用 urls.URLize
报错看不懂 解码后仍是乱码 对已经编码过的字符串再次编码(双重编码) 先确认输入是否已编码,再决定是否调用本函数

更多排查入口见故障排查。