デプロイ後に白画面？ デバッグの実践ガイド

自分のマシンでは完璧に動いていたアプリをデプロイし、URLを開いたら、どこまでも丁寧で、どこまでも何もない画面が待っていた。これはAIが作ったアプリで最もよくある障害パターンのひとつです。ただ安心してほしいのは、白画面はまず謎ではないということ——原因は少数のどれかひとつで、どこを見ればいいかを知っていればブラウザが教えてくれます。以下のリストを上から順に試していきましょう。白画面の大半は最初の2つのチェックで片づきます。

まず、コードに触れる前にコンソールを開く

DevTools（F12、または右クリック→検証）を開き、コンソールタブに切り替えてページを再読み込みします。空白のシングルページアプリなら、ほぼ確かに赤いJavaScriptエラーや失敗したネットワークリクエストが表示されます。次にネットワークタブを開いてもう一度再読み込みし、赤い行——404で返ってきたものや、想定外のコンテンツタイプのもの——を探します。そのメッセージはコピーしておいてください。それが診断結果であり、AIエージェントに渡して修正を依頼するための材料そのものです。以下は、目の前にあるかもしれない症状との対応表になっています。

ビルド後のアセットパスの誤り

バンドラーはインポートを /assets/index-a1b2c3.js のような、サイトルートからの絶対パスに書き換えます。サブディレクトリにデプロイすると——GitHub Pages で /repo-name/ の下に置いた場合や、ベースパスの背後で配信する場合——ブラウザはドメインルートの /assets/... を要求し、404、あるいは最悪の場合JavaScriptの代わりになるHTMLエラーページを受け取って、何も描画しなくなります。症状：ネットワークタブにハッシュ付きファイル名への404が並んでいる。修正：バンドラーのベースパス（Vite では base、他のツールにも同様の設定があります）をアプリの実際の配置場所に合わせて設定し、ビルドし直して再デプロイする。

古いキャッシュが死んだバンドルを配信している

ハッシュ付きファイル名はビルドのたびに変わりますが、index.html は通常その名前のままです。CDN、ホスト、あるいは自分のブラウザがそのHTMLのキャッシュ版を配信すると、サーバーにはもう存在しないJavaScriptファイルを参照してしまう——結果、白画面。症状：現在のビルドのものとは思えないチャンク名への404、あるいはプライベートウィンドウでは普通に動くのに通常のウィンドウでは動かない。修正：CDNキャッシュをパージし、HTMLには短いキャッシュ有効期間を送らせ、ハッシュ付きアセットだけを長期キャッシュさせるようにしてから、強制リロードする。ロールバック直後や高速な再デプロイ直後にいちばん罠にはまりやすい。

SPAフォールバックルーティングの欠如

シングルページアプリはURLをクライアント側ででっち上げています。/dashboard/settings のようなネストしたルートを直接開く——アドレスを入力したり、そのページでリフレッシュしたり、ディープリンクをたどったり——と、サーバーは存在しないはずのリテラルなファイルを探しに行きます。多くのホストは自前の404ページを返します。さらに空っぽのものを返すホストもあります。トップページは表示されるのにディープリンクだけが白画面またはエラーになるなら、これが原因です。修正：未知のパスをすべてindex.htmlに書き換えるようホストを設定する。主要な静的ホストはすべて、何らかの名前——リライト、フォールバックルール、シングルページアプリモード——でこの機能をサポートしています。

MIMEタイプと厳格なモジュール読み込み

最近のバンドルはESモジュールとしてロードされ、ブラウザはコンテンツタイプを厳格に確認します。text/plain や text/html として配信された .js ファイルはそのまま拒否され、場合によってはアプリ全体が沈黙したまま停止します。症状：MIMEタイプに関するコンソールエラーや「Failed to load module script」。これはホストのコンテンツタイプ設定の誤りや、スクリプトの代わりに200ステータスで返ってくるソフト404のHTMLページでよく起きます。修正：正しいJavaScriptのコンテンツタイプで配信されるよう設定したホスティングから静的ファイルを配信し、失敗しているURLがエラーページではなく、実際にコードを返していることを確認する。

ビルド時に焼き込まれた環境変数

Viteなどのフレームワークは、VITE_ プレフィックス付きの変数をビルド時にバンドルへインライン展開し、ローカルのシェルや .env ファイルから読み込みます。その値を設定せずに同じビルドを別環境へデプロイすると、それらを参照するコードは undefined を得ます：どこにも向いていないAPIコール、初期化されないままの認証、そして白画面。症状：未定義の設定に言及するコンソールエラー、または不正なURLへのネットワークリクエスト。修正：デプロイ環境のビルドステップで変数を設定し、その場でビルドし直す——これらの値はバンドル生成の時点で存在している必要があり、実行時だけでは足りない。

証拠をエージェントに渡す

コンソール出力さえ手に入れば、これはもう謎ではなく修正依頼になります。コンソールエラーやネットワークの失敗をエージェントのセッションに貼り付け、原因を追わせましょう——設定を読み、ビルドを再現し、自分の修正を検証する、というのはまさに エージェンティックコーディングとは で述べたループです。デプロイパイプライン自体がまだよく分からないなら、ホスティング設定を一つずつ試行錯誤する代わりに、AIで作ったアプリのデプロイ方法 から始めることをおすすめします。

meshcodeならではの解決

meshcodeはMacとWindows向けのネイティブデスクトップアプリで、各ペインが同じリポジトリ上でそれぞれ独立したエージェントセッションを動かします——ひとつのペインがビルド設定を読み解く間に、別のペインがデプロイ済みアセットとレスポンスヘッダーを確認する、互いに邪魔をしない並行作業です。すでに持っているClaude CodeやCodex CLIのサブスクリプションを持ち込めば、追加のトークン費用なしで使えます。まだの方は、月額費用ゼロの従量課金制のmeshcode内蔵モデルから始められます。

👉 meshcodeをダウンロード — Mac、Windows