Hugo aliases 怎么用？旧 URL 自动跳转与 404 修复指南

Sun, 17 May 2026 20:00:17 +0800

Hugo 的 aliases 用来给页面创建旧 URL 跳转。

当你修改文章链接、合并页面、迁移博客，或者想修复某个常见的错误 URL 时，可以在文章的 Front Matter 里添加 aliases。Hugo 会为这些旧地址生成跳转页面，把访问者带到当前文章的新地址，避免旧链接直接变成 404。

aliases 适合解决什么问题

最常见的场景有三类。

第一类是优化文章链接。

例如，你原来的文章地址是：

`1`	`/posts/tech/2023-01-01-hello/`

后来想改成更短的地址：

/hello/

这时可以给新文章加上旧地址 alias。这样搜索引擎、外部引用、社交平台旧链接仍然能访问到内容。

第二类是合并或迁移页面。

如果你把几篇旧文章合并到一篇新文章，或者从 Hexo、Typecho、WordPress 等平台迁移到 Hugo，旧平台的 URL 结构往往和新站不同。aliases 可以把这些旧地址逐个指向新页面，降低迁移后的 404 数量。

第三类是处理拼写错误。

有些 URL 可能曾经写错，或者外部网站已经引用了错误路径。如果这个错误链接有访问量，可以为它单独设置 alias，让用户仍然能跳到正确页面。

基本写法

只需要在文章 Front Matter 中添加 aliases 字段。

下面是 YAML 格式示例：

---
title: "新文章标题"
date: 2026-05-17T12:00:00+09:00
url: /new-path/my-new-article/
aliases:
  - /old-path/old-article/
  - ../old-version/
---

这里的 /old-path/old-article/ 是站点相对路径。../old-version/ 则是相对当前页面的路径。

实际使用时，更推荐优先使用站点相对路径，也就是以 / 开头的路径。它更直观，也更不容易因为文章目录结构变化而产生误判。

和 url 字段的关系

url 决定当前页面的新地址。

aliases 决定哪些旧地址会跳转到这个新地址。

例如：

1
2
3

url: /new-path/my-new-article/
aliases:
  - /old-path/old-article/

构建后，用户访问 /old-path/old-article/，会被跳转到 /new-path/my-new-article/。

如果文章没有显式设置 url，Hugo 会按照站点的 permalinks 配置、文章日期、slug 等规则生成当前页面地址。aliases 仍然会指向这个最终生成的页面。

Hugo 默认怎么实现跳转

默认情况下，Hugo 会为每个 alias 生成一个独立的 HTML 文件。

这个 HTML 文件通常会使用：

`1`	`<meta http-equiv="refresh">`

让浏览器打开旧地址后自动跳转到新地址。

这种方式简单、跨平台，适合普通静态托管环境。但它本质上是浏览器端跳转，不是服务端返回的 301 / 302 重定向。

对小站点来说，这通常已经够用。只要旧地址能打开，并且最终能到达新文章，就可以避免明显的 404 问题。

什么时候考虑服务端重定向

如果站点部署在 Netlify、Cloudflare Pages、Vercel 或其他支持重定向规则的平台上，可以考虑用服务端重定向。

服务端重定向的优势是：

响应更直接，不需要先返回一个 HTML 跳转页。
更容易明确使用 301 或 302 状态码。
对大量迁移规则更集中，方便审计和维护。
对 SEO 迁移更可控。

一种常见做法是禁用 Hugo 默认 alias 页面生成，再输出平台需要的重定向规则文件。例如 Netlify 常用 _redirects，Cloudflare Pages 可以使用 _redirects 或平台自己的规则配置。

如果你走这条路线，需要在 Hugo 配置中研究 disableAliases 和自定义 output format。不要只删掉 aliases，否则旧链接会直接变成 404。

使用 aliases 的注意事项

第一，不要把 aliases 当成随意改 URL 的借口。

URL 一旦公开，就会进入搜索引擎、RSS、社交平台、书签和外部引用。频繁修改 URL 会制造维护成本。aliases 更适合修复历史问题，而不是鼓励经常改路径。

第二，避免 alias 互相循环。

旧地址应该指向当前文章的新地址，不要让 A 跳 B、B 又跳 A，也不要让多个页面争用同一个 alias。

第三，多语言站点要注意语言前缀。

Hugo 多语言站点通常会自动处理语言路径。如果你在某个语言版本里写 alias，有时不需要手动加 /en/、/zh-tw/ 这类前缀。否则可能生成重复路径，例如 /en/en/...。具体行为要以本地构建结果为准。

第四，修改后要检查生成目录。

添加 alias 后，可以构建一次站点，再检查 public 目录里是否生成了旧路径对应的 index.html，并确认其中的目标链接是否正确。

一个实用检查流程

修改文章 Front Matter 后，可以按下面流程检查：

确认当前文章的新 URL。
在 aliases 中写入旧 URL。
运行 Hugo 构建。
到 public 目录检查旧 URL 对应的 index.html 是否生成。
打开生成的 HTML，确认跳转目标是否是新 URL。
如果是多语言页面，特别检查是否出现重复语言前缀。

这样可以在部署前发现大部分路径问题。

小结

aliases 是 Hugo 里处理旧链接的轻量工具。

它最适合用在文章改 URL、博客迁移、页面合并和错误路径修复这些场景。普通静态站点可以直接使用 Hugo 默认生成的 HTML 跳转页；如果站点规模较大，或对 SEO 迁移要求更高，可以进一步改成服务端重定向规则。

真正关键的是：不要只关注新链接是否好看，也要照顾已经存在的旧链接。一个能把旧 URL 平稳带到新页面的站点，才不容易在迁移和改版时丢掉历史流量。

重定向 on KnightLi的博客