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 平穩帶到新頁面的站點，才不容易在遷移和改版時丟掉歷史流量。

Aliases on KnightLi的博客