Build Modeを初めて触った日のことは、今でも鮮明に覚えています。「プロンプト1行でアプリが生成できる」という触れ込みに期待しながら試してみたところ、プレビューパネルが真っ白なまま5分以上動かなかったのです。リロードしても変わらず、何が起きているのか手がかりすらなかった。
個人開発を続けてきた身として、新しいツールの初回起動でハマることは珍しくありません。ただBuild Modeの場合、問題が複数のレイヤー（ブラウザ・Firebaseプロジェクト・生成コード・デプロイ設定）にまたがるため、原因の切り分けに時間がかかりやすい。
Build Modeで実際によく起きるエラーを場面ごとに整理し、それぞれの根本原因と対処法を実例とともに整理しました。
プレビューが真っ白のまま動かない
Build Modeを開いてプロンプトを送ったのに、右パネルが白いままになることがあります。これは最もよく報告される問題の一つで、原因は主に3つあります。
原因1: JavaScriptのランタイムエラー
生成されたコードにシンタックスエラーや未定義変数への参照が含まれていると、プレビュー用のiframeがレンダリングに失敗して真っ白になります。確認方法はブラウザのDevToolsを開くことです。
手順:
1. Build Modeのプレビューパネルが表示されている状態でF12（DevTools）を開く
2. 「Console」タブを選択
3. 赤いエラーメッセージが出ていれば、それが原因
よく出るエラーの例:
TypeError: Cannot read properties of undefined (reading 'map')
このエラーはデータフェッチ前にリストを.map()しようとしたときに出ます。Geminiが生成したコードではローディング状態のハンドリングが省略されることがあります。以下のパターンで修正を依頼できます。
プロンプト例:
「データ読み込み中のローディング状態を適切に処理して。undefined チェックも追加して。」
原因2: ブラウザの拡張機能による干渉
広告ブロッカーやコンテンツスクリプト系の拡張機能が、Build Modeのiframe通信をブロックすることがあります。シークレットモード（拡張機能が無効になる）で試して問題が解消すれば、拡張機能が原因です。
確認手順:
1. Ctrl+Shift+N（Mac: Cmd+Shift+N）でシークレットウィンドウを開く
2. aistudio.google.com にアクセスしてBuild Modeを再試行
3. プレビューが表示されれば拡張機能を一つずつ無効化して特定する
原因3: セッションの期限切れ
Google AI StudioはGoogleアカウントのセッションが切れると、APIコールが失敗してプレビューが動かなくなることがあります。ページを閉じて再ログインしてから試してみてください。
プロンプトを送っても変更が反映されない
「ボタンの色を青にして」「フォントを大きくして」と送っても、コードとプレビューが変わらないケースがあります。
これは多くの場合、コンテキストの肥大化が原因です。Build Modeでは会話履歴を持ったまま編集を続けていくと、Geminiが参照しているコンテキストが巨大になり、小さな変更指示が「すでに処理済み」として無視されることがあります。
解消方法は2つあります。
一つ目は「Reset Context」を使うこと。Build Modeの会話履歴の上部にあるリセットボタンを押すと、コードを保持したまま会話履歴だけをクリアできます。
二つ目は指示をより具体的にすること。曖昧な指示より、変更箇所を特定した指示のほうが確実に反映されます。
❌ 曖昧な指示:
「もっとシンプルにして」
✅ 具体的な指示:
「ヘッダーコンポーネントの背景色を #1a73e8 に変更して。
ボタンのpadding を 8px 16px にして。」
Firebase連携後にアプリが動かない
Build ModeからFirebaseにデプロイした後、本番環境でアプリが動かないことがあります。典型的なパターンが2つあります。
パターン1: 環境変数が未設定
生成コードがFirebase SDK の設定情報を環境変数から読み込むように書かれていても、Firebase Hostingには環境変数の仕組みがありません。process.env.VITE_FIREBASE_API_KEY のような記述はローカル開発では動くものの、Hostingにデプロイするとundefinedになります。
// 生成コードにこのような記述があると本番で失敗する
const firebaseConfig = {
apiKey: process.env.VITE_FIREBASE_API_KEY, // Hosting では undefined
authDomain: process.env.VITE_FIREBASE_AUTH_DOMAIN,
};解決策は設定値を直接コードに埋め込むか（公開プロジェクトの場合はFirebase API Keyは公開情報なので問題なし）、Firebase App Hostingのシークレット機能を使うかです。
// Firebase API Key はフロントエンドで公開される前提の設計（認証はFirebase側が担保）
const firebaseConfig = {
apiKey: "AIzaSy_YOUR_ACTUAL_KEY", // ← ここに直接記載して問題ない
authDomain: "your-project.firebaseapp.com",
projectId: "your-project-id",
};パターン2: Firebaseのセキュリティルール未設定
Firestoreにデータを書き込もうとして「permission-denied」エラーが出る場合、Firestoreのセキュリティルールがデフォルト（全拒否）のままになっています。
Firebase Console → Firestore Database → ルール
以下を開発中の一時設定として使い、リリース前に適切なルールに絞り込みます。
// 開発用（本番では必ず認証ベースのルールに変更すること）
rules_version = '2';
service cloud.firestore {
match /databases/{database}/documents {
match /{document=**} {
allow read, write: if request.auth != null;
}
}
}生成コードを手動編集した後にBuild Modeが壊れる
「Code」タブでコードを手動編集した後、再度プロンプトで変更を依頼すると、手動編集した部分が上書きされたり、コードが壊れたりすることがあります。
Build ModeのGeminiは、プロンプトを送るたびに全コードを再生成するわけではなく、差分パッチを適用します。ただし手動編集した部分がパッチの適用範囲と衝突すると、予期しない挙動になることがあります。
このケースの対処法はコメントで意図を明示することです。
// ★ この関数は手動で最適化済み — Geminiに変更させないこと
function customCalculation(data) {
// ...重要なロジック
}また、大きな手動変更を加えた後は「このコードを基準として、〇〇の機能を追加して」とプロンプトで明示的に伝えると、既存コードを尊重した変更になりやすいです。
GitHub連携でコードが消えた
Build ModeのGitHub Export機能を使ってリポジトリに連携した後、再度Build ModeからPushすると、既存のカスタマイズが上書きされることがあります。
現時点のBuild ModeのGitHub連携は「一方向の上書き」として設計されています。つまり、GitHubで加えた変更はBuild Modeには反映されません。この前提を理解した上で、使い方を次のように変えると安全です。
推奨フロー:
1. Build Modeで大枠を生成
2. GitHubにExport（ここから先はコードを「卒業」させる）
3. ローカルにcloneして通常の開発フローに移行
4. Build Modeには戻らない（または新しいブランチで試験的に使う）
個人開発では「Build Modeでプロトタイプ、その後ローカル開発」という分業が現実的です。個人開発を長く続けてきた経験でも、ツールの設計意図に沿った使い方をするほうが、無理に拡張するより長期的にうまくいくことが多いと感じます。
ビルドが終わらない（タイムアウト）
複雑なアプリをプロンプト1回で生成しようとすると、Geminiの生成が途中で止まることがあります。特に「ECサイトを全機能込みで作って」のような大きな要求は、タイムアウトや不完全な生成につながりやすいです。
解決策は段階的に構築することです。
Step 1: 「シンプルな商品一覧ページだけ作って」
Step 2: 「カートに追加する機能を追加して」
Step 3: 「Stripe決済を組み込んで」
Step 4: 「Firebase Authでログイン機能を追加して」
一度に求める量を減らすことで、生成の精度も上がります。個人的には「1プロンプトで1機能」を意識するようになってから、Build Modeのハマりがほとんどなくなりました。
Firebase 自動連携で「裏側に何ができるか」を知っておく
Build Mode で「データを保存したい」「ログインさせたい」と伝えると、Antigravity エージェントがバックエンドの要否を判断し、Firebase 連携を提案します。ここで「承認」を押した瞬間に何が自動で作られるかを把握しておくと、前述の permission-denied や本番で設定が消える類の不具合を、未然に切り分けられます。
承認すると、裏側で次の4つがまとめて実行されます。
- Firebase プロジェクトの新規作成（既存プロジェクトの選択も可能）
- Cloud Firestore の有効化と、初期セキュリティルールの自動設定
- Firebase Authentication の有効化と Google プロバイダーの登録
- 生成コードへの Firebase SDK の組み込み
この自動処理には数十秒かかることがあります。プレビューが一瞬止まったように見えても、プロジェクト作成中であれば異常ではありません。DevTools のコンソールにエラーが出ていなければ、まず数十秒は待ってみてください。
承認した直後に確認しておきたいのは、次の3点です。これだけで、後から permission-denied やデプロイ後の不具合に遭ったときの原因切り分けが速くなります。
承認後のチェックリスト:
1. Firebase Console でどのプロジェクトが作られたか（既存と取り違えていないか）
2. Firestore → ルール が初期設定（緩い一時ルール）のままになっていないか
3. Authentication → Sign-in method で Google プロバイダーが有効か
特に2点目は注意してください。自動設定される初期ルールは開発用に緩めてあることが多く、そのまま公開すると誰でも読み書きできてしまいます。前述のセキュリティルールの節を参考に、リリース前に認証ベースのルールへ必ず絞り込んでください。
個人開発では、Build Mode に任せる範囲と自分で締める範囲の線引きを最初に決めておくと、後戻りが減ります。私自身、自動生成された緩いルールを本番直前まで見落とし、公開前のチェックでようやく気づいて冷や汗をかいたことがあります。
全体を振り返って
Build Modeのエラーは多くの場合、生成コードの品質問題・Firebase設定の抜け・プロンプトの粒度の3つに帰結します。DevToolsのコンソールを開く習慣をつけると、原因特定が格段に速くなります。
まず試してほしいのはシークレットモードでBuild Modeを開いてみることです。これだけで拡張機能起因の問題は確認できます。そこからコンソールのエラーを確認して、一つずつ潰していく流れが、個人的には一番回り道が少ないと思っています。