Vite/React アプリケーションを GitHub Pages にデプロイすることはエキサイティングなマイルストーンですが、このプロセスでは、特に画像やアセットを扱う場合、予期せぬ課題が発生することがあります。このブログ投稿では、初期導入から一般的な問題のトラブルシューティング、効果的な解決策の発見までのプロセス全体を説明します。

初心者でも経験者でも、このガイドはよくある落とし穴を回避し、すべてのアセットが適切にレンダリングされた状態で Vite/React アプリを正常にデプロイするのに役立ちます。

前提条件

本題に入る前に、次のものが揃っていることを確認してください:

• Vite/React プロジェクト: このガイドは、ビルド ツールとして Vite、フレームワークとして React を使用してプロジェクトを設定していることを前提としています。
• GitHub リポジトリ: アプリケーションをプッシュして展開する既存の GitHub リポジトリが必要です。
• GitHub Pages が有効になっています: デプロイ用のリポジトリの設定で GitHub Pages が有効になっていることを確認してください。

ステップ 1: プロジェクトと GitHub Pages のデプロイメントを初期化する

まず、Vite/React アプリケーションが適切に初期化され、ローカルホスト上で動作することを確認します。次のように基本的な Vite プロジェクトを作成できます:

npm create vite@latest

依存関係のインストール:

npm install

プロジェクトをローカルで実行して、すべてが機能することを確認します:

npm run dev

プロジェクトの準備ができたら、GitHub リポジトリにプッシュします。

GitHub ページ用の vite.config.js を作成する

GitHub Pages は、アプリケーションが特定のベース URL (通常はリポジトリ名) から提供されることを想定しています。これを反映するように vite.config.js ファイルを更新します:

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

export default defineConfig({
  base: process.env.NODE_ENV === 'production' ? '/your-repo-name/' : '/',
  plugins: [react()],
})

base オプションにより、アプリケーションがデプロイ時に正しいベース パスを使用することが保証されます。

ステップ 2: プロジェクトをビルドしてデプロイする

展開を処理するには、gh-pages パッケージをインストールする必要があります。

npm install gh-pages --save-dev

package.json に次のスクリプトを追加して、展開プロセスを自動化します:

"scripts": {
  "predeploy": "npm run build",
  "deploy": "gh-pages -d dist"
}

デプロイメントを実行します:

npm run deploy

この時点で、プロジェクトは https://.github.io// で公開されているはずですが、あなたが私と同じ場合は、いくつかの問題が発生する可能性があります。アプリが適切にレンダリングされないか、画像が表示されません。

ステップ 3: 一般的な問題と解決策

問題 1: 導入後の空白ページ

展開後、アプリが空のページを読み込むことに気づくかもしれません。これは多くの場合、ルーティングの問題が原因で発生します。デフォルトでは、react-router-dom の BrowserRouter が使用され、サーバー側のルーティングに依存しますが、GitHub Pages は静的ファイルを提供し、クライアント側のルートを処理しません。

解決策: HashRouter を使用する

これを解決するには、index.js または main.jsx ファイルで BrowserRouter から HashRouter に切り替えます。

注: これは、私がプロジェクトで頻繁に使用する便利な UI ライブラリであるため、必ずしも持っている必要はありません。

import { HashRouter } from 'react-router-dom';

createRoot(document.getElementById('root')).render(
  
);

HashRouter は、URL でハッシュ記号 (#) を使用してナビゲーション状態を追跡し、GitHub Pages が 404 を返さずにさまざまなルートを適切に提供できるようにします。

問題 2: 更新またはその他のルートでの 404 エラー

空白のページの問題を解決した後、直面する可能性のある別の問題は、アプリがホームページで動作しているものの、他のルートに移動すると、特に /blogs や /projects などのルートに直接アクセスすると 404 エラーが表示されることです。

これは、GitHub Pages がindex.html ファイルの提供方法しか認識しておらず、React Router によって管理されるルートを認識しないために発生します。

解決策: GitHub ページの設定で 404 エラーを処理する

これを修正するには、public/ フォルダーに 404.html ファイルを作成する必要があります。このファイルにより、GitHub Pages が認識しないルートに対して Index.html ファイルを提供し、React Router がルーティングを処理できるようになります:

1. index.html を 404.html という名前の新しいファイルにコピーします。
2. このファイルを public/ フォルダーに配置します。
3. プロジェクトを再ビルドして再デプロイします。

問題 3: 本番環境に画像が読み込まれない

最も一般的な展開の問題の 1 つは、イメージが正しく読み込まれないことです。 localhost では正常に動作しますが、GitHub Pages にデプロイした後、画像リンクが壊れていることに気づく場合があります。

たとえば、コンポーネント内で次のような画像を参照できます:

問題: 間違った画像パス

ここでの問題は、アプリがサブディレクトリ (例: /your-repo-name/) にデプロイされている場合、絶対パス (/ で始まる) がうまく機能しないことです。 GitHub Pages は、https://.github.io/your-repo-name/Images/myImage.png ではなく https://.github.io/Images/myImage.png でイメージを検索しようとします。 404 エラーが発生します。

解決策: BASE_URL

これを修正するには、すべての画像を Public/Images に移動します。これはオプションですが、そうすることを強くお勧めします。環境に基づいて BASE_URL を画像パスの先頭に動的に追加します:

1. 環境に依存する BASE_URL 定数を定義します:

   const BASE_URL = import.meta.env.BASE_URL;

1. 画像を参照する場合は、この BASE_URL を使用してください:

注: Images の前にある / を削除することを忘れないでください。削除しないと、BASE_URL からの 1 つと、削除し忘れた /Images からの 2 つになってしまいます。

これにより、開発 (localhost) と運用環境 (GitHub Pages) の両方で正しいパスが使用されるようになります。

ステップ 4: 最終的な展開

ルーティングとイメージ パスの修正を実装した後、アプリケーションを再構築して再デプロイします:

npm run build
npm run deploy

これで、Vite/React アプリケーションが完全にデプロイされ、すべての画像が正しくレンダリングされ、すべてのルートが適切に処理されるはずです。

要約すれば：

1. ルーティングの問題: GitHub Pages などの静的デプロイメントで適切なルーティングを行うには HashRouter を使用してください。
2. ルート上の 404 エラー: 404.html ファイルを作成して、GitHub Pages がアプリを正しく提供できるようにします。
3. 画像が読み込まれていません: すべての画像を Public/Images に移動し、アセット パスに BASE_URL を動的に追加して、開発環境と運用環境の両方を処理します。

これらの手順により、Vite/React アプリは GitHub Pages 上で稼働し、スムーズに機能するようになります。コーディングとデプロイを楽しんでください!