1. はじめに
Reactの学習を進める中で、アウトプットを目的にSPA（Single Page Application）をGitHub Pagesにデプロイしてみた。
しかし、トップページは表示されるものの、他のルート（例：/aboutや/contact）にアクセスすると**「404 Not Found」**エラーが発生することに気づいた。
調査を進めた結果、原因はルーティングの実装に使用していた BrowserRouter にあった。
この問題は HashRouter に切り替えることで解決できたが、なぜBrowserRouterでは動作せず、HashRouterでは問題なく動作するのか、その仕組みを理解する必要があると感じた。
本記事では、
-
GitHub PagesでBrowserRouterが動かない理由
-
HashRouterが動作する仕組み
について整理し、同じように悩んでいる方の参考になるようにまとめていく。
対象読者： React初心者〜中級者、GitHub PagesでSPAを公開したい人。
2. GitHub Pagesの仕組みを理解する
まず、なぜBrowserRouterが動かないのかを理解するには、GitHub Pagesのホスティング構造を知る必要がある。
GitHub Pagesは「静的ホスティングサービス」であり、ビルド後のHTML・CSS・JavaScriptファイルをそのまま配信するだけの仕組みになっている。
つまり、サーバー側でルーティングやリダイレクトを制御する仕組みが存在しない。
たとえば、次のようなSPAをデプロイしたとする：
/
├── index.html
├── /static
│ ├── main.jsx
│ └── styles.css
トップページ（/）を開くとindex.htmlが正しく返されるが、
/aboutに直接アクセスすると、サーバーはabout/index.htmlを探しにいき、ファイルが存在しないため404エラーを返してしまう。
3. BrowserRouterが動作しない理由
BrowserRouterを使用したルーティングは、ブラウザ上では/aboutというURLを表示しても、実際には同じindex.html上でReactがページを切り替えている。
しかし、GitHub Pagesのようにサーバーがすべてのリクエストをindex.htmlにリダイレクトしてくれない環境では、ユーザーが直接/aboutを開いた際に「そのファイルが存在しない」と判断されてしまう。
一方で、VercelやNetlify、Cloudflare Pagesといったモダンなホスティングサービスでは、
SPA用に「すべてのリクエストをindex.htmlへリダイレクトする」設定（fallback）がデフォルトで有効になっており、問題なく動作する。
4. HashRouterで解決する仕組み
HashRouterはURLの#（ハッシュ）を使ってクライアントサイドでルーティングを行う。
例：
https://username.github.io/myapp/#/about
ブラウザは#以降をサーバーに送信しないため、常にindex.htmlが返されるという仕組みである。
Reactはその後、ハッシュ部分（例：#/about）を見てどのコンポーネントを表示するか判断する。
そのため、GitHub Pagesのような静的サーバーでも問題なく動作する。
実装例：
import { HashRouter, Routes, Route, Link } from "react-router-dom";
import Home from "./Home";
import About from "./About";
export default function App() {
return (
<HashRouter>
<nav>
<Link to="/">Home</Link>
<Link to="/about">About</Link>
</nav>
<Routes>
<Route path="/" element={<Home />} />
<Route path="/about" element={<About />} />
</Routes>
</HashRouter>
);
}
この方法を使えば、GitHub Pagesでも正しくページ遷移が動作する。
また、プログラム上でリンクを実装する上では、#を含む必要はない。HashRouterを使う場合、URLには#が含まれるようになります。
⚠️ 注意点：外部リンクやSEO対策
HashRouterで生成されるURL（#/aboutなど）は検索エンジンによるクロールが弱い傾向があります。
SEOを重視したい場合は、GitHub PagesではなくNetlifyやVercelなど、BrowserRouterが使えるホスティングを選ぶのがおすすめです。