【GitHub Pages】React Routerを使うとエラーになる？basename設定で解決

はじめに

こんにちは。アメリカ在住で独学エンジニアを目指している Taira です。
ReactアプリをGitHub Pages（以下GHP）にデプロイしたのに、
トップページは表示できるのにリンク先で真っ白になったり404が出たり…という経験はありませんか？

実はこれは React Routerの仕様とGitHub Pagesの仕組みが噛み合っていない ことが原因です。
この記事では、その理由と、basename の設定で確実に動かす方法を紹介します。

---

なぜReact RouterはGitHub Pagesでうまく動かないのか？

React Routerは「クライアントサイドルーティング」を採用しています。
つまり、ページ遷移を行うときも、実際には新しいHTMLファイルをサーバーから取得するのではなく、
1枚のindex.html上でURLだけを切り替えて表示を制御しています。

一方、GitHub Pagesは静的ホスティングサービスです。
そのため、たとえば /about にアクセスすると about というフォルダやファイルを探しに行ってしまい、
存在しないために404になってしまいます。

さらに、GHPの「プロジェクトサイト」では、
公開URLが https://username.github.io/<repo>/ のように サブパス（/<repo>/） が必ず付くため、
React Routerがこのサブパスを認識していないとリンクの解決ができません。

この2つが組み合わさって、
GHP × React Routerでは「リンク先が真っ白」などの現象が起きるわけです。

---

今回紹介するのは「プロジェクトサイト」の場合

GitHub Pagesには2種類の公開パターンがあります。

種類	公開URL	basename 必要？
ユーザーサイト	https://username.github.io/	❌ 不要
プロジェクトサイト	https://username.github.io/<repo>/	✅ 必要

あなたが多分つまずいているのは プロジェクトサイト の方です。
今回はこの プロジェクトサイトの方を紹介します。

---

解決法：basenameを設定する

basename は、React Routerに
「このアプリは /repo 配下で動いているよ」と教えるための設定です。
Viteの場合、ビルド設定のbaseと合わせて設定することで正しく動作します。

---

1. vite.config.ts に base を追加

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  base: '/<repo>/', // ← 公開先のパスを指定（末尾スラッシュ必須）
})

💡 補足
base は「公開されるURLのパス部分」を指定します。
ここではリポジトリ名を例にしていますが、
実際には 公開先のURLに合わせて自由に設定できます。

たとえば：

• https://username.github.io/portfolio/ → base: '/portfolio/'
• https://example.com/app/ → base: '/app/'
• https://example.com/（直下） → base: '/'

---

2. BrowserRouter に basename を追加

// main.tsx
import React from 'react'
import ReactDOM from 'react-dom/client'
import { BrowserRouter } from 'react-router-dom'
import App from './App'

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <BrowserRouter basename="/<repo>">
      <App />
    </BrowserRouter>
  </React.StrictMode>
)

basename の先頭には / を、末尾にはスラッシュを付けないのがポイントです。
たとえば、リポジトリ名が portfolio の場合は：

• Viteのbase: /portfolio/
• Routerのbasename: /portfolio

この2つをセットで合わせることで、
リンク先のパスやアセットが正しく解決されるようになります。

---

これで完成！

npm run build でビルド → gh-pages などでデプロイすれば、
https://username.github.io/<repo>/ でReact Routerが正常に動作するようになります。

---

まとめ

設定項目	設定値	補足
vite.config.ts の base	'/<repo>/'	実際の公開パスに合わせてOK
BrowserRouter の basename	'/<repo>'	末尾スラッシュなし
公開URL	https://username.github.io/<repo>/	GHPプロジェクトサイト用