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には#が含まれるようになります。

Home → https://username.github.io/myapp/#/
About → https://username.github.io/myapp/#/about

⚠️ 注意点：外部リンクやSEO対策

HashRouterで生成されるURL（#/aboutなど）は検索エンジンによるクロールが弱い傾向があります。

SEOを重視したい場合は、GitHub PagesではなくNetlifyやVercelなど、BrowserRouterが使えるホスティングを選ぶのがおすすめです。