GitHub Pagesにデプロイする際に画面と顔が真っ白になった

どうも、初心者です

今回初めて記事を投稿することになったTetracontaneです。
今回投稿した理由は、初めて記事を投稿するTetracontaneです。今回、GitHub Pagesへのデプロイ時に真っ白な画面に直面することが多く、毎回場当たり的な対処をしていたため、根本的な原因を理解することにしました。

環境

• Windows 11
• npm + vite + react

原因

最初にお伝えしておきますが、重要なのは「パスの設定」です。開発サーバー（npm run dev）では正しく表示されるのに、デプロイ後には表示されない場合は、ほぼ確実にパスの設定ミスが原因です(5敗)。

• package.json
• vite.config.js

このどちらか（または両方）のパスを変更すると、デプロイ時にうまくいくと思います。

そもそも、そこはビルド時に分かるのでは？

これがなぜかわからなかったです。ローカルでのビルド時では成功しても、GitHub Actions側ではうまくいかなかったりしました。

これを解決するために探した結果以下の情報が出てきました。

• package.jsonの"homepage"を"homepage": "./"にする
• package.jsonの"homepage"を"homepage": "https:username.github.io/repository"にする
• vite.config.jsのbaseをbase: 'https:username.github.io/repository'にする
  それぞれの検証結果は以下の通りでした。

package.jsonの"homepage"を"homepage": "./"にする

結果:

省略 ...
<link rel="stylesheet" crossorigin href="/assets/index-DiwrgTda.css">
省略

なんで？
せっかくhomepageを"./"にしたのに"/"で統一されてしまっている。

package.jsonの"homepage"を"homepage": "https:username.github.io/repository"にする

結果:

省略 ...
<link rel="stylesheet" crossorigin href="/assets/index-DiwrgTda.css">
省略

なんで？(2回目)
何も変わっていないのが少し悔しい。

vite.config.jsのbaseをbase: 'https:username.github.io/repository'にする

3度目の正直ということで、package.json以外の変更をしてみようと調べたところ、viteもベースとなるURLをいじれるらしい

結果:

省略 ...
<link rel="stylesheet" crossorigin href="https:username.github.io/repository/assets/index-DiwrgTda.css">
省略

嬉しい！

この3つの結果からの仮説

• viteを使う際、パスに関してはpackage.jsonは関与しない
• base+ファイル内での相対パスがビルド後のパス

仮説の検証

vite.config.jsonのbaseを'./'にしてみる

結果:

省略 ...
<link rel="stylesheet" crossorigin href="./assets/index-DiwrgTda.css">
省略

結論

viteを使う際はpackage.jsonではなく、vite.config.jsのbaseを編集しよう！

補足

なぜそうなるのかを考えたとき、Viteはビルドツールであり、package.jsonはパッケージに関するメタデータを含むものなので、package.jsonにはメタデータを記述し、ビルド関連の設定はvite.config.jsにまとめるのが良いと予測しました。