GitHub Pages SPA 404ヘルパーとは
GitHub Pagesは静的ファイルを配信し、一致するファイルが存在しない限りクライアントサイドルートを認識しません。シングルページアプリケーションでは、訪問者がディープルートを直接開くと404が表示されることがあります。404フォールバックは、リクエストされたパスをルーター用に保持しながら、ブラウザをアプリのエントリポイントにリダイレクトできます。
クイックアンサー
GitHub Pagesにデプロイされたシングルページアプリケーション向けの404.htmlフォールバックを生成します。フォールバックはディープクライアントサイドルートをアプリのエントリポイントにリダイレクトし、元のパスをルーターが処理できるよう保持します。
Last updated: 2026-06-11
制限事項
- これは汎用的なクライアントサイドフォールバックであり、サーバーサイドリダイレクト設定ではありません。ブラウザ内のJavaScriptに依存して元のパスを抽出し、ルーターに渡します。
- クライアントサイドルーターは、クエリ文字列またはハッシュから保持されたパスを読み取り、一致するルートをレンダリングするよう設定する必要があります。すべてのルーターがこのリダイレクトパターンを自動的に処理するわけではありません。
- このアプローチは、最初のリダイレクト後のSPA内のナビゲーションやリフレッシュ動作を修正しません。完全なクライアントサイドルーティングサポートには、ルーターレベルの設定が依然として必要です。
Sources:MDN Web Docs · W3C Specifications · jquery.app on GitHub
使い方
- アプリのベースパスを入力します。ユーザードメインまたはカスタムドメインサイトには/を、プロジェクトページには/repo-name/を使用します。
- フォールバックが元のパスをクエリ文字列とハッシュのどちらに保存するかを選択します。
- 生成された404.htmlファイルを公開サイトルートにコピーします。
- デプロイ後にディープルートを直接テストします。
主な用途
- GitHub Pages上のクライアントサイドルートへの直接訪問を修正する。
- React、Vue、Svelte、バニラルーター向けの404フォールバックを準備する。
- プロジェクトページに必要なベースパスを文書化する。