React（Vite）をレンタルサーバーへ公開したら真っ白になる原因と対処法

2026-08-132026-09-05

ReactとViteで作成したWebサイトがローカル環境では正常に動作しているのに、レンタルサーバーへアップロードすると画面が真っ白になることがあります。

白い画面だけが表示されると、アップロードそのものに失敗したように見えます。しかしReactアプリの場合、index.htmlは正常に届いている一方で、JavaScriptの読み込みや実行に失敗しているケースが少なくありません。

この記事では、ViteでビルドしたReactアプリが公開環境で真っ白になった場合の原因と、確認する順序を整理します。

まず試すこと

公開直後に画面が真っ白になった場合は、最初にブラウザのスーパーリロードを試します。

Windowsでは次のキーを押します。

Ctrl + F5

通常の再読み込みでは、ブラウザに保存された古いHTML、JavaScript、CSSがそのまま使われる場合があります。Ctrl + F5を使用すると、キャッシュを無視して必要なファイルを再取得できます。

それでも直らない場合は、シークレットウィンドウまたは別のブラウザで公開URLを開きます。そこで正常に表示されるなら、サーバー側ではなくブラウザキャッシュが原因である可能性が高いと判断できます。

Reactアプリが真っ白になる仕組み

一般的なReactアプリのindex.htmlには、画面の内容がほとんど書かれていません。

<body>
  <div id="root"></div>
</body>

このroot要素へ、JavaScriptがReactの画面を生成します。

したがって、次のような状態になると、HTML自体は表示できても画面には何も描画されません。

JavaScriptファイルが見つからない
JavaScriptを取得できない
JavaScriptの実行中にエラーが発生した
古いHTMLと新しいJavaScriptが混在した
新しいHTMLが、まだアップロードされていないファイルを参照した

画面が真っ白でも、必ずしもindex.htmlのアップロードに失敗しているとは限りません。

原因1：ブラウザキャッシュ

最も簡単に解決できる原因です。

公開ファイルを更新しても、ブラウザが以前取得したファイルを保持していると、新旧のファイルが混在することがあります。

確認方法は次のとおりです。

Ctrl + F5で再読み込みする
シークレットウィンドウで開く
別のブラウザまたは端末で開く

いずれかで正常に表示された場合は、公開ファイルではなくキャッシュの問題と考えられます。

原因2：index.htmlとassetsの世代が一致していない

Viteでnpm run buildを実行すると、通常はdistフォルダに公開用ファイルが生成されます。

dist/
├── assets/
│   ├── index-AbCd1234.js
│   └── index-EfGh5678.css
├── favicon.svg
└── index.html

index-AbCd1234.jsのようにファイル名へ付加される文字列は、内容をもとに生成されるハッシュです。コードやCSSが変わると、次回のビルドでは別のファイル名になることがあります。

前回：index-AbCd1234.js
今回：index-XyZ98765.js

新しいindex.htmlだけを先にアップロードすると、そのHTMLは新しいJavaScriptを参照します。しかし、対応するJavaScriptがまだサーバーに存在しなければ、ブラウザはファイルを取得できません。

新しい index.html
        ↓ 参照
まだ存在しない新しいJavaScript
        ↓
Reactを起動できず白画面

安全なアップロード順序

手動でレンタルサーバーへアップロードする場合は、次の順序にすると一時的な不整合を減らせます。

1. assetsフォルダの中身
2. favicon.svgなどの静的ファイル
3. index.htmlを最後に上書き

ポイントは、index.htmlを最後に更新することです。

また、distフォルダ自体をドキュメントルートへ置くのではなく、通常はdistの中身をアップロードします。

公開ディレクトリ/
├── assets/
├── favicon.svg
└── index.html

次のように一段深く配置すると、想定したURLからファイルを参照できない場合があります。

公開ディレクトリ/
└── dist/
    ├── assets/
    └── index.html

原因3：JavaScriptやCSSのアップロード漏れ

ブラウザの開発者ツールを開き、Networkタブを確認します。

ChromeやEdgeでは、一般にF12キーで開発者ツールを表示できます。ページを再読み込みし、JavaScriptやCSSの状態を確認します。

次のような応答があれば、ファイルの配置または参照先に問題があります。

404 Not Found
403 Forbidden
500 Internal Server Error

特に、index.htmlに記載されたJavaScriptのファイル名と、サーバーのassetsフォルダにあるファイル名が一致しているか確認します。

正常な場合は、JavaScriptとCSSが概ね次のような状態になります。

200 application/javascript
200 text/css

原因4：Viteのbase設定が公開先と合っていない

Viteは、アプリをどのURL階層へ配置するかによってbase設定が必要になることがあります。

サブドメインのルートへ公開する場合は、通常はルート相対パスで問題ありません。

https://tools.example.com/

一方、次のようなサブディレクトリへ公開する場合は注意が必要です。

https://example.com/tools/

この場合はvite.config.tsで公開パスを設定します。

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

export default defineConfig({
  plugins: [react()],
  base: '/tools/',
})

baseが合っていないと、ブラウザがJavaScriptやCSSを別の場所へ探しに行き、404になることがあります。

なお、サブドメインのルートへ公開する場合と、親ドメインのサブディレクトリへ公開する場合は別物です。公開URLを基準に設定を判断します。

原因5：SPAルーティングが設定されていない

React Routerなどを使用しているSPAでは、トップページからの画面遷移は動いても、ツールのURLを直接開いたり再読み込みしたりすると404や500になる場合があります。

例えば次のURLです。

https://tools.example.com/tools/calculator

サーバーはtools/calculatorという実ファイルを探します。しかし、その画面はReactが生成するものであり、サーバー上に同名のHTMLファイルはありません。

Apache系のレンタルサーバーで.htaccessが利用できる場合は、存在しないパスをindex.htmlへ内部転送します。

<IfModule mod_rewrite.c>
RewriteEngine On

RewriteRule ^index\.html$ - [L]

RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^ index.html [L]
</IfModule>

これにより、実在するJavaScript、CSS、画像などはそのまま配信し、それ以外の画面URLはReactへ渡せます。

レンタルサーバーによって使用可能なディレクティブや設定方法が異なるため、実際の設定は契約中のサーバー仕様も確認してください。

原因6：JavaScriptの実行時エラー

JavaScriptファイルが200 OKで取得できていても、実行中に例外が発生するとReactの描画が止まることがあります。

開発者ツールのConsoleタブを確認し、赤色のエラーがないか調べます。

代表例は次のとおりです。

未定義の変数や関数を参照している
読み込んだJSONの構造が想定と異なる
環境変数がビルド時に設定されていない
大文字と小文字がファイル名で一致していない
開発環境にしか存在しないファイルを参照している

Windowsではファイル名の大文字・小文字の違いに気づきにくく、Linux系サーバーへ公開して初めて問題になることがあります。

Tools.json
tools.json

Linux系環境では、上記を別のファイルとして扱うのが一般的です。

確認する順序

白画面の原因を効率よく絞り込むには、次の順序で確認します。

1. Ctrl + F5でスーパーリロード
2. シークレットウィンドウで確認
3. index.htmlが取得できるか確認
4. NetworkでJS・CSSのHTTPステータスを確認
5. ConsoleでJavaScriptエラーを確認
6. index.htmlとassetsのファイル名を照合
7. Viteのbase設定を確認
8. 直接URLを再読み込みしてSPAルーティングを確認

この順序なら、単なるキャッシュ問題と、公開ファイルや設定の問題を分けて判断できます。

公開後の動作確認項目

アップロード後はトップページを見るだけでなく、最低限次を確認します。

トップページが表示される
JavaScriptとCSSが正常に読み込まれる
リンクから各画面へ移動できる
各画面のURLを直接開ける
各画面で再読み込みしても表示される
入力を変更すると計算結果や表示が更新される
PCとスマートフォンの両方で大きく崩れない
Consoleにアプリ由来のエラーが出ていない

特に「トップから遷移できる」ことと「直接URLを開ける」ことは別々に確認する必要があります。

古いassetsはすぐに削除しない

公開更新時に古いassetsをすぐ削除すると、古いindex.htmlをキャッシュしている利用者が旧JavaScriptを取得できなくなる場合があります。

小規模サイトを手動更新する段階では、新しい公開版の動作を確認してから古いハッシュ付きファイルを整理する方が安全です。

ただし、更新を繰り返すと不要ファイルが増えるため、どのindex.htmlからも参照されなくなった旧アセットは、バックアップを確保したうえで定期的に整理します。

まとめ

ReactとViteで作成したサイトが公開後に真っ白になる場合、HTMLが届いていてもJavaScriptが起動できていない可能性があります。

まずは次の3点を確認します。

Ctrl + F5でキャッシュを更新する
JS・CSSが200で取得できているか確認する
index.htmlとassetsの世代を一致させる

手動アップロードでは、assetsを先に配置し、index.htmlを最後に上書きすると不整合を減らせます。

それでも解決しない場合は、base設定、SPAルーティング、ConsoleのJavaScriptエラーを順番に確認します。

白画面を一つの原因で決めつけず、HTMLの取得、アセットの取得、JavaScriptの実行、ルーティングという層に分けて確認することが、最短の解決につながります。

参考になったらシェアしてください

URLをコピーしました！

URLをコピーしました！

この記事を書いた人

ekplabz

機械設計・油圧・CAD・Python・AIなど、ものづくりに関わる技術を扱っています。工学知識を整理・構造化し、設計や自動化に再利用できる形へ変えていくことを目指しています。