URL 函数 on Hugo 中文文档

urls.AbsLangURL

Fri, 02 Oct 2026 00:00:00 +0800

单语言与多语言配置都可以使用该函数。返回的 URL 取决于：

输入是否以斜杠（/）开头
项目配置中的 baseURL
语言前缀（如果有）

下文示例使用这份项目配置：

defaultContentLanguage = 'en'
defaultContentLanguageInSubdir = true
[languages.en]
weight = 1
[languages.es]
weight = 2

输入不以斜杠开头

如果输入不以斜杠开头，结果 URL 中的路径相对于项目配置里的 baseURL。

urls.AbsURL

Fri, 02 Oct 2026 00:00:00 +0800

使用多语言配置时，请改用 urls.AbsLangURL 函数。返回的 URL 取决于：

输入是否以斜杠（/）开头
项目配置中的 baseURL

输入不以斜杠开头

如果输入不以斜杠开头，结果 URL 中的路径相对于项目配置里的 baseURL。

urls.Anchorize

Fri, 02 Oct 2026 00:00:00 +0800

anchorize 与 urlize 两个函数很相似：

用 anchorize 函数生成 HTML id 属性的值
用 urlize 函数把字符串清理为可用于 URL 的形式

例如：

{{ $s := "A B C" }}
{{ $s | anchorize }} → a-b-c
{{ $s | urlize }} → a-b-c

{{ $s := "a b   c" }}
{{ $s | anchorize }} → a-b---c
{{ $s | urlize }} → a-b-c

{{ $s := "< a, b, & c >" }}
{{ $s | anchorize }} → -a-b--c-
{{ $s | urlize }} → a-b-c

{{ $s := "main.go" }}
{{ $s | anchorize }} → maingo
{{ $s | urlize }} → main.go

{{ $s := "Hugö" }}
{{ $s | anchorize }} → hugö
{{ $s | urlize }} → hug%C3%B6

urls.Anchorize 函数会按项目配置中的 autoIDType 设置清理结果字符串。

urls.JoinPath

Fri, 02 Oct 2026 00:00:00 +0800

{{ urls.JoinPath }} → "" (empty string)
{{ urls.JoinPath "" }} → /
{{ urls.JoinPath "a" }} → a
{{ urls.JoinPath "a" "b" }} → a/b
{{ urls.JoinPath "/a" "b" }} → /a/b
{{ urls.JoinPath "https://example.org" "b" }} → https://example.org/b

{{ urls.JoinPath (slice "a" "b") }} → a/b

与 path.Join 函数不同，urls.JoinPath 会保留开头连续的斜杠。

urls.Parse

Fri, 02 Oct 2026 00:00:00 +0800

urls.Parse 函数把 URL 解析为一个 URL 结构体。URL 可以是相对形式（一条路径，没有主机名），也可以是绝对形式（以方案开头）。解析无效 URL 时 Hugo 会抛出错误。

{{ $url := "https://example.org:123/foo?a=6&b=7#bar" }}
{{ $u := urls.Parse $url }}

{{ $u.String }} → https://example.org:123/foo?a=6&b=7#bar
{{ $u.IsAbs }} → true
{{ $u.Scheme }} → https
{{ $u.Host }} → example.org:123
{{ $u.Hostname }} → example.org
{{ $u.RequestURI }} → /foo?a=6&b=7
{{ $u.Path }} → /foo
{{ $u.RawQuery }} → a=6&b=7
{{ $u.Query }} → map[a:[6] b:[7]]
{{ $u.Query.a }} → [6]
{{ $u.Query.Get "a" }} → 6
{{ $u.Query.Has "b" }} → true
{{ $u.Fragment }} → bar

urls.PathEscape

Fri, 02 Oct 2026 00:00:00 +0800

（0.153.0 新增）

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

{{ urls.PathEscape "my café" }} → my%20caf%C3%A9

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

urls.PathUnescape

Fri, 02 Oct 2026 00:00:00 +0800

（0.153.0 新增）

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

{{ urls.PathUnescape "A%2Fb%2Fc%3Fd=%C3%A9&f=g+h" }} → A/b/c?d=é&f=g+h

用该函数解码 URL 路径中的单个片段。

urls.Ref

Fri, 02 Oct 2026 00:00:00 +0800

用法

ref 函数接受两个参数：

用于解析相对路径的上下文（通常是当前页面）。
目标页面的路径，或一个选项映射（见下文）。

选项

path: （string）目标页面的路径。不以斜杠（/）开头的路径会先相对于当前页面解析，再相对于站点其余部分解析。
lang: （string）目标页面的语言。默认为当前语言。可选项。
outputFormat: （string）目标页面的输出格式。默认为当前输出格式。可选项。

示例

下面的示例展示英语版站点上某个页面的渲染输出：

urls.RelLangURL

Fri, 02 Oct 2026 00:00:00 +0800

单语言与多语言配置都可以使用该函数。返回的 URL 取决于：

输入是否以斜杠（/）开头
项目配置中的 baseURL
语言前缀（如果有）

下文示例使用这份项目配置：

defaultContentLanguage = 'en'
defaultContentLanguageInSubdir = true
[languages.en]
weight = 1
[languages.es]
weight = 2

输入不以斜杠开头

如果输入不以斜杠开头，结果 URL 相对于项目配置里的 baseURL。

urls.RelRef

Fri, 02 Oct 2026 00:00:00 +0800

用法

relref 函数接受两个参数：

用于解析相对路径的上下文（通常是当前页面）。
目标页面的路径，或一个选项映射（见下文）。

选项

path: （string）目标页面的路径。不以斜杠（/）开头的路径会先相对于当前页面解析，再相对于站点其余部分解析。
lang: （string）目标页面的语言。默认为当前语言。可选项。
outputFormat: （string）目标页面的输出格式。默认为当前输出格式。可选项。

示例

下面的示例展示英语版站点上某个页面的渲染输出：

urls.RelURL

Fri, 02 Oct 2026 00:00:00 +0800

使用多语言配置时，请改用 urls.RelLangURL 函数。返回的 URL 取决于：

输入是否以斜杠（/）开头
项目配置中的 baseURL

输入不以斜杠开头

如果输入不以斜杠开头，结果 URL 相对于项目配置里的 baseURL。

baseURL = https://example.org/ 时

{{ relURL "" }}                         → /
{{ relURL "articles" }}                 → /articles
{{ relURL "style.css" }}                → /style.css
{{ relURL "https://example.org" }}      → https://example.org
{{ relURL "https://example.org/" }}     → /
{{ relURL "https://www.example.org" }}  → https://www.example.org
{{ relURL "https://www.example.org/" }} → https://www.example.org/

baseURL = https://example.org/docs/ 时

urls.URLize

Fri, 02 Oct 2026 00:00:00 +0800

anchorize 与 urlize 两个函数很相似：

用 anchorize 函数生成 HTML id 属性的值
用 urlize 函数把字符串清理为可用于 URL 的形式

例如：

{{ $s := "A B C" }}
{{ $s | anchorize }} → a-b-c
{{ $s | urlize }} → a-b-c

{{ $s := "a b   c" }}
{{ $s | anchorize }} → a-b---c
{{ $s | urlize }} → a-b-c

{{ $s := "< a, b, & c >" }}
{{ $s | anchorize }} → -a-b--c-
{{ $s | urlize }} → a-b-c

{{ $s := "main.go" }}
{{ $s | anchorize }} → maingo
{{ $s | urlize }} → main.go

{{ $s := "Hugö" }}
{{ $s | anchorize }} → hugö
{{ $s | urlize }} → hug%C3%B6

用 urlize 函数可以创建指向术语页面（term page）的链接。