React2Static
ブログに戻る

Google AI Studio アプリがデプロイ後に真っ白になる理由と直し方

React2Static Team
公開日 2026-07-28
7 分で読めます
Google AI StudioTroubleshootingDeployViteReact404Static Site

Google AI Studio アプリをデプロイしたら真っ白な画面や404に？原因はほぼ次の4つのどれかです——ビルド、ベースパス、API キー、SPA のルーティング。それぞれの直し方を解説します。

なぜデプロイ後に真っ白になるのか

AI Studio のプレビューでは動いていた、もしかしたらローカルでも動いていたアプリが、デプロイしたら真っ白な画面や404になった——原因は、ほとんどの場合、次の4つのどれかです。どれもアプリ自体が壊れているわけではありません。確認しやすい順に見ていきます。始める前にブラウザの開発者コンソールを開いておくと、どれに当てはまるか大抵わかります。

1. ビルドではなくソースをデプロイしてしまった

一番よくある原因です。AI Studio から取得できるのはプロジェクトフォルダですが、ホスティング先が必要としているのはビルド後の成果物です。package.json や src/ フォルダ、vite.config.ts をそのままアップロードすると、ホスティング先はそのままでは実行できないソースを配信することになり、真っ白な画面になります。

直し方: まずプロジェクトをビルドし、生成された dist/ フォルダをデプロイしてください——フォルダの中身であって、プロジェクト全体ではありません。React2Static はブラウザ内でそのビルドを実行し、アップロードできる状態の dist/ フォルダを渡してくれます。Netlify や Cloudflare Pages では、ビルド後のフォルダをドラッグしてください。プロジェクトフォルダそのものは絶対にドラッグしないでください。

2. 真っ白な画面で、JS と CSS ファイルが404になっている

コンソールを確認してください。/assets/index-abc123.js のようなファイルが404になっている場合、ページ自体は表示されていますが、必要なスクリプトを取得できていません。アプリがファイルをサイトのルートから取得しようとしているのに、実際は別の場所でホスティングされているのです。これはGitHub Pagesでよく起きます。GitHub Pages のプロジェクトサイトは / ではなく /your-repo/ から配信されるためです。

直し方: vite.config.ts の base パスを、アプリが実際に置かれている場所に合わせてください。ルートドメインなら "/"、GitHub Pages のプロジェクトサイトなら "/your-repo/" です。

// vite.config.ts
export default defineConfig({
  base: '/your-repo/',
});

変更後に再ビルドしてください。ドメインのルートや *.pages.dev / *.netlify.app のサブドメインでホスティングしている場合は、デフォルトの "/" のままで正しいので——だからこそ Cloudflare Pages や Netlify にデプロイすればこの問題自体を回避できます。

3. 「API キーが undefined」または AI 機能が何も反応しない

アプリ自体は読み込まれるものの、Gemini を呼び出す部分がすべて失敗する場合です。これには2つのパターンがあります。

  • ホスティング先で環境変数が設定されていない。 ホスティング先の設定画面で追加してください——Netlify なら Site settings の中の Environment variables、Cloudflare Pages なら Settings の中の Environment variables です。コードが期待する変数名と完全に一致させてから再デプロイしてください。
  • 変数は設定されているが、その値が本来公開してはいけないシークレットになっている。 フロントエンドの JavaScript に埋め込まれたキーは、サイトを開いた誰にでも読める状態です。非公開のデモならそれでも構いませんが、公開するものであれば、Gemini の呼び出しは小さな serverless 関数(Netlify Functions や Cloudflare Workers)経由にし、キーがサーバー側にとどまってブラウザまで届かないようにしてください。

    • 自分のビルドにキーが含まれていないか不安な場合は、React2Static がダウンロード前にプロジェクトを走査して露出したシークレットを検出し、警告してくれます。公開してから気づくのではなく、事前に気づけます。

    4. トップページは動くのに、他のページをリロードすると404になる

    アプリがクライアントサイドルーティング(React Router など)を使っています。最初のアクセスは index.html から始まるのでうまくいきますが、/about をリロードすると、ホスティング先は /about という実ファイルを探しに行き、見つからずに404を返します。

    直し方: 未知のパスに対して index.html を返すよう、ホスティング先に指示してください。

  • Netlify — デプロイするフォルダに _redirects ファイルを追加します。
    • /*    /index.html   200
  • Cloudflare Pages — デフォルトで、未知の SPA ルートに対して index.html を返します。うまく動かない場合は、同じ _redirects のルールを追加してください。
  • GitHub Pages — このようなフォールバックがありません。アプリをハッシュルーティングに切り替えるか、index.html を 404.html としてコピーしてください。

    • ヒント: AI Studio アプリの中には最初から HashRouter を使っているもの(URL に # が含まれるもの)もあり、これならこの問題自体が起きません。

    より安全な既定パターン: 先に静的ファイルへエクスポートする

    この4つの問題のうち3つは、根本的な原因が同じです。ソースをそのままデプロイしてしまった、あるいは、ビルド済みファイルを前提とするホスティング先にソースを配置してしまった、というものです。先に静的ファイルへビルドし、それをルートから配信してくれるホスティング先にデプロイすれば、こうしたリスクの大半はそもそも発生しません。この流れは Google AI Studio アプリを無料でデプロイする(Cloud Run 不要) で説明しています。まだ慣れていない場合は、先に アプリをローカルで動かして 動作を確認してから公開すると安心です。

    FAQ

    Google AI Studio アプリがデプロイ後に真っ白になるのはなぜですか？

    多くの場合、ビルド後の dist/ フォルダではなくソースフォルダをアップロードしてしまっているか、ビルドのベースパスがホスティング先と合っていないことが原因です。環境変数の設定漏れと SPA のルーティングも、よくある原因の残り2つです。

    JavaScript ファイルで404エラーが出るのはなぜですか？

    アプリがホスティングされている場所に対して base パスが合っていません。ルートドメインなら vite.config.ts の base を "/" に、GitHub Pages のプロジェクトサイトなら "/your-repo/" に設定し、再ビルドしてください。

    ページをリロードすると404になるのはなぜですか？

    クライアントサイドルーティングでは、未知のパスに対してホスティング先が index.html にフォールバックする必要があります。Netlify や Cloudflare Pages では _redirects のルールを追加するか、GitHub Pages ではハッシュルーティングを使ってください。

    デプロイしたアプリに Gemini API キーを直接置いても安全ですか？

    いいえ——フロントエンドのコードに置いたキーは、サイトを開いた誰からでも見える状態になります。公開するものであれば、serverless 関数を経由して Gemini を呼び出し、キーをサーバー側にとどめてください。

    ブログに戻る