Aliases
返回前置元数据中定义的别名,形式为服务器相对 URL,并按当前内容维度解析。
这一页解决什么问题
页面改名或改变路径之后,旧链接不能失效。Hugo 的常规做法是在前置元数据里写 aliases,由 Hugo 为每个别名生成一个跳转 HTML;而 Aliases 方法把这份清单读回模板,让你自己生成服务器级重定向文件(_redirects、.htaccess),或对别名做检查。
Page 对象上的 Aliases 方法返回 aliases 前置元数据字段中定义的值,形式为服务器相对 URL,并按当前内容维度解析。
Aliases 方法适合用来生成 _redirects 文件:其中为每个别名给出源 URL、目标 URL 与 HTTP 状态码。Cloudflare、GitLab Pages、Netlify 等托管服务都可以使用 _redirects 文件。
什么时候用,什么时候别用
该用:
- 托管服务商支持
_redirects或.htaccess,你想在服务器层处理跳转,而不是让浏览器先加载一个中转页——这正是下一节「重定向」的场景; - 想在构建时校验别名:遍历
hugo.Sites的每个页面,取出.Aliases逐条检查重复、空白字符或冲突; - 只想知道某个页面挂了哪些别名。
别用:
- 只是想让旧 URL 跳到新 URL:在前置元数据里写
aliases就够了,Hugo 默认会生成跳转页,不需要写任何模板; - 想拿当前页面的 URL:用
.RelPermalink(服务器相对)或.Permalink(绝对 URL),与别名无关; - 想在模板中新增别名:
Aliases只是只读返回值,别名只能来自前置元数据。
重定向
默认情况下,Hugo 通过为每个别名路径分别创建一个 HTML 文件来处理别名。这些文件含有 meta http-equiv="refresh" 标签,由浏览器完成对访问者的重定向。
这种做法确实可用,但生成单个 _redirects 文件可以让托管服务商在服务器层面处理重定向。它比客户端重定向更高效,也省去了加载一个中转 HTML 页面的开销,从而提升性能。
示例
下面的示例演示如何配置站点,并创建一个模板来自动生成 _redirects 文件。
内容结构
这个多语言示例的内容结构如下:
content/
├── examples/
│ ├── a.de.md aliases = ['a-old']
│ ├── a.en.md aliases = ['a-old', 'a-older']
│ ├── b.de.md aliases = ['b-old']
│ └── b.en.md aliases = ['b-old', 'b-older']
└── _index.md上例中的别名是页面相对的。要指定站点相对路径,请在条目开头加上斜杠(/)。两种写法最终都会解析为服务器相对路径。
页面相对路径还可以包含目录跳转:
| 路径类型 | 文件路径 | 别名 | 服务器相对路径 |
|---|---|---|---|
| 页面相对 | content/examples/a.en.md |
a-old |
/en/examples/a-old/ |
| 页面相对 | content/examples/a.en.md |
../a-old |
/en/a-old/ |
| 站点相对 | content/examples/a.en.md |
/a-old |
/en/a-old/ |
项目配置
为此,你必须修改项目配置:
- 将
disableAliases设为true,以禁用默认的 HTML 重定向文件生成。 - 定义一种名为
text/redirects的媒体类型来处理该文件格式。 - 定义一种名为
redirects的自定义输出格式,把文件名设为_redirects,并把它放到发布站点的根目录。 - 配置首页的输出,在
html之外再加上redirects格式。
baseURL = 'https://example.org/'
disableAliases = true
defaultContentLanguage = 'en'
defaultContentLanguageInSubdir = true
[languages.en]
locale = 'en-US'
direction = 'ltr'
name = 'English'
weight = 1
title = 'My Site in English'
[languages.de]
locale = 'de-DE'
direction = 'ltr'
name = 'Deutsch'
weight = 2
title = 'My Site in German'
[mediaTypes]
[mediaTypes.'text/redirects']
delimiter = ''
[outputFormats]
[outputFormats.redirects]
baseName = '_redirects'
isPlainText = true
mediaType = 'text/redirects'
root = true
[outputs]
home = ['html', 'redirects']模板实现
接下来,为 redirects 输出格式单独创建一个首页模板。下面的模板会遍历每种语言的每个页面,并提取其别名。
为确保生成的 _redirects 文件有效,该模板用 strings.FindRE 函数检查别名字符串中是否存在制表符、换行符等空白字符。一旦检测到空白,Hugo 会抛出错误并中止构建,以免生成无效文件。
{{- if site.IsDefault -}}
{{- range hugo.Sites -}}
{{- range $p := .Pages -}}
{{- range .Aliases -}}
{{- if findRE `\s` . -}}
{{- errorf "One of the front matter aliases in %q contains whitespace" $p.String -}}
{{- end -}}
{{- printf "%s %s 301\n" . $p.RelPermalink -}}
{{- end -}}
{{- end -}}
{{- end -}}
{{- end -}}生成的输出
Hugo 处理该模板后,会产出一份干净的重定向规则列表。每一行都遵循规定的格式:源 URL、目标 URL 与 HTTP 状态码。
生成的 _redirects 文件如下:
/de/examples/a-old /de/examples/a/ 301
/de/examples/b-old /de/examples/b/ 301
/en/examples/b-old /en/examples/b/ 301
/en/examples/b-older /en/examples/b/ 301
/en/examples/a-old /en/examples/a/ 301
/en/examples/a-older /en/examples/a/ 301完整示例:在模板里列出页面的别名
最小站点:content/docs/guide/alpha.md 的前置元数据里有 aliases = ['a-old', '/site-old'],同目录的 beta.md 没有任何别名。把下面的代码放进 layouts/_default/single.html:
{{ if .Aliases }}
<p>本页别名:{{ delimit .Aliases "、" }}</p>
{{ else }}
<p>本页没有别名</p>
{{ end }}hugo --source <站点目录> --ignoreCache 构建后,渲染 alpha 得到:
<p>本页别名:/docs/guide/a-old、/site-old</p>渲染 beta(没有别名)得到:
<p>本页没有别名</p>你应当看到什么:页面相对的写法 a-old 被解析为 /docs/guide/a-old,即拼在当前页面所在目录之后;站点相对的写法 /site-old 原样保留。两者都不带末尾斜杠(上游表格把它们写作 /en/examples/a-old/,实测返回值不含末尾斜杠)。同一次构建还会在 public/docs/guide/a-old/index.html 与 public/site-old/index.html 生成跳转页,内容形如:
<!DOCTYPE html>
<html lang="en-US">
<head>
<title>https://example.org/docs/guide/alpha/</title>
<link rel="canonical" href="https://example.org/docs/guide/alpha/">
<meta charset="utf-8">
<meta http-equiv="refresh" content="0; url=https://example.org/docs/guide/alpha/">
</head>
</html>返回值边界(实测)
测量条件:Hugo 0.167.0 extended,Windows;baseURL = 'https://example.org/',未设置 disableAliases。
| 情况 | 结果 | 是否报错 |
|---|---|---|
前置元数据中没有 aliases |
空切片,len 为 0,if / with 判为假 |
否 |
一个页面相对别名(页面在 content/docs/guide/) |
一个元素:/docs/guide/a-old |
否 |
一个站点相对别名(以 / 开头) |
一个元素:/site-old |
否 |
| 多个别名 | 顺序与前置元数据中出现的先后一致 | 否 |
设置了 disableAliases = true |
切片内容不变,但不再生成跳转 HTML(这正是上游示例的用法) | 否 |
| 返回类型 | []string,元素是服务器相对路径 |
否 |
常见坑
| 类别 | 症状 | 真因 | 怎么修 |
|---|---|---|---|
| 没报错但结果不对 | 把别名和相对路径拼接,得到 /docs/guide/a-old/docs/guide/alpha/ |
别名本身已是可以直接跳转的服务器相对路径 | 直接输出别名元素,目标页单独用 .RelPermalink |
| 没报错但结果不对 | 以为别名带末尾斜杠,字符串比对总是失败 | 实测返回值不带末尾斜杠 | 比较前先规范化(补 / 或用 strings.TrimSuffix) |
| 没报错但结果不对 | _redirects 文件里混入空白字符,服务商拒绝 |
别名中混进了制表符或换行 | 按上游示例用 findRE 检查并 errorf 中止构建 |
| 什么都没输出 | range .Aliases 空转 |
该页没有定义 aliases,返回空切片 |
用 if / with 给兜底文案 |
更多排查入口见故障排查。