Hugo aliases の使い方：古い URL の自動リダイレクトと 404 修正ガイド

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

Hugo の aliases は、ページの古い URL に対してリダイレクトを作るための機能だ。

記事の URL を変更したとき、ページを統合したとき、ブログを移行したとき、またはよくある誤った URL を救済したいとき、記事の Front Matter に aliases を追加できる。Hugo はそれらの古いアドレス用にリダイレクトページを生成し、訪問者を現在の記事の新しいアドレスへ送る。これにより、古いリンクがそのまま 404 になるのを避けられる。

aliases が役立つ場面

よくある場面は三つある。

一つ目は記事 URL の整理だ。

たとえば、元の記事 URL が次のようなものだったとする。

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

後から、より短い URL に変えたい場合がある。

/hello/

このとき、新しい記事に古いアドレスを alias として追加する。すると検索エンジン、外部リンク、SNS 上の古いリンクからも内容へ到達できる。

二つ目はページの統合や移行だ。

複数の古い記事を一つの新しい記事にまとめる場合や、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、SNS、ブックマーク、外部リンクに入っていく。頻繁な 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ブログ