エディタのプレビューが正常に動作しても、公開後のサイトが空白になることがあります。この違いは、本番環境、ビルドされたアセット、またはライブルーティングに問題があることを示しており、むやみなデザイン変更とは関係ありません。

30秒での解決策

ライブURLを開き、ブラウザの開発者ツールを開き、再読み込みを行います。最初の赤い コンソール エラーと最初の失敗した ネットワーク リクエストをもとに、以下の分岐を選択してください：

  • 環境変数が不足しているか undefined → 配置ホストに追加し、再デプロイ
  • JavaScriptまたはCSSが404を返す → ビルド出力またはパブリックベースパスを修正
  • Unexpected token < またはモジュールMIMEエラー → URLがJavaScriptではなくHTMLを返した
  • ネストされたURLのみがリロード後に失敗 → ホストのドキュメントに記載されているSPAフォールバックを追加
  • JavaScriptがアプリがマウントされる前に例外をスロー → その最初のランタイム例外を修正

分岐1 — プロダクション変数が不足している

アプリビルダー内に保存されたシークレットは、すべての外部ホストに自動的に存在しません。プロジェクト内の変数 名前 を、正確なプロダクション環境で設定された変数と比較してください。チャットやスクリーンショットにシークレット値をコピーしないでください。

クライアントサイドのViteアプリの場合、フレームワークのパブリックプレフィックスで意図的に公開された変数のみがブラウザコードで利用可能です。空白画面を消すためにサーバーのキーを公開しないでください。変数をデプロイメントプラットフォームで追加または修正し、新しいデプロイメントを作成してください。変数を変更しても、既存のビルドは再構築されません。

分岐2 — ビルドされたアセットが不足している

ネットワークパネルで、失敗したJavaScriptまたはCSSリクエストを選択します。404は、デプロイされた出力と生成されたアセットURLが一致していないことを意味します。Unexpected token < は、スクリプトURLがHTMLエラーページを返したことを示します。モジュールMIMEエラーは、ソースファイルがアップロードされた代わりにコンパイルされた出力がアップロードされたことを意味します。

ローカルでクリーンなプロダクションビルドを実行してください：

bash

npm run build

フレームワークが実際に生成するディレクトリをデプロイしてください。たとえば、標準のViteプロジェクトでは dist/ です。プラットフォームの現在のビルド出力設定を使用し、フォルダ名を推測しないでください。アプリがサブパスの下で提供されている場合、フレームワークのパブリックベースパスをその実際のURLと比較してください。

分岐3 — ネストされたルートがリロード後に失敗する

もし / が正常に動作するが、/dashboard が空白または404になる場合、ブラウザルーターとホストが一致していない可能性があります。ホスティングプラットフォームのドキュメントに記載されているシングルページアプリフォールバックを設定し、アプリケーションルートが index.html を返すようにしてください。アセットファイルやAPIルートを index.html にリダイレクトしないでください。それにより、上記の Unexpected token < エラーが発生する可能性があります。

リライトがデプロイされた後、直接アクセスとリロードの両方を1つのネストされたルートでテストしてください。

分岐4 — ライブアプリがランタイムエラーをスローする

最初の例外から始めて、その下のすべてのメッセージを確認しないでください。典型的な例は、undefined からプロパティを読み取ること、必要なURLを指定せずにAPIクライアントを初期化すること、またはブラウザ機能が利用可能であると仮定してコードをインポートすることです。

エージェントに正確な例外、ファイル名、行番号を提供してください。その値が欠如している理由を説明してもらうように求め、修正後、新しいビルドを行い、シークレットウィンドウでライブURLを再テストしてください。

修正を確認する

新しいデプロイメントを使用して確認してください：

  1. デプロイメントビルドが成功したか
  2. ライブコンソールに最初のロード時に未処理の例外が表示されていないか
  3. JavaScriptおよびCSSリクエストが期待されるコンテンツタイプで成功レスポンスを返しているか
  4. / と1つのネストされたルートがシークレットウィンドウで動作しているか
  5. メインのインタラクションが動作しているか、最初のフレームだけではなく

キャッシュされたタブは古い失敗を表示する可能性があります。最終的な確認にはシークレットウィンドウまたは強制リロードを使用してください。

それでも解決しない場合

最後に正常に動作したデプロイメントを復元し、その環境変数名、ビルドコマンド、出力ディレクトリ、ルーティングルールを失敗したデプロイメントと比較してください。プロバイダーがインシデントを報告している場合、コードの変更を停止し、待機してください。それ以外の場合は、サポートにデプロイメントURL、最初のコンソールエラー、最初の失敗したネットワークリクエスト、およびデプロイメントログを送信してください（シークレットや個人データは削除してください）。

初心者向けのまとめ

プレビューが正常に動作するが、公開後のサイトが白い場合、ライブ環境が異なっている可能性があります。最初の赤いコンソールエラーを確認し、ホストに必要な変数が存在することを確認し、コンパイルされた出力結果をデプロイし、ネストされたURLをテストしてください。AIにページを再構築させるのではなく、1つの分岐ずつ変更してください。