Warum deine Google-AI-Studio-App nach dem Deploy leer bleibt (und wie du es behebst)

Warum das passiert

Deine App lief in der AI-Studio-Vorschau, vielleicht sogar lokal, und dann hast du sie deployed und bekommst nur eine leere Seite oder einen 404. Das liegt fast immer an einem von vier Gründen, und keiner davon bedeutet, dass die App kaputt ist. Hier sind sie, sortiert danach, was du am schnellsten prüfen kannst, – öffne die Entwicklerkonsole deines Browsers, bevor du anfängst, denn die verrät dir meist, welcher Fall bei dir zutrifft.

1. Du hast den Quellcode deployed, nicht den Build

Die häufigste Ursache. AI Studio gibt dir einen Projektordner; ein Hoster braucht die gebaute Ausgabe. Wenn du package.json, einen src/-Ordner und vite.config.ts hochgeladen hast, liefert der Hoster ungebauten Quellcode aus, den er nicht ausführen kann – daher die leere Seite.

Fix: Bau das Projekt zuerst, und deploye dann den entstandenen dist/-Ordner – dessen Inhalt, nicht das ganze Projekt. React2Static führt diesen Build in deinem Browser aus und gibt dir den dist/-Ordner fertig zum Hochladen. Bei Netlify oder Cloudflare Pages ziehst du den gebauten Ordner rein, nie den Projektordner.

2. Leere Seite mit 404s bei den JS- und CSS-Dateien

Schau in die Konsole. Siehst du 404s für Dateien wie /assets/index-abc123.js, hat sich die Seite geladen, aber ihre Skripte nicht: Die App fordert ihre Dateien vom Site-Root an, sie liegen aber woanders. Das passiert vor allem bei GitHub Pages, wo eine Projektseite unter /your-repo/ statt unter / ausgeliefert wird.

Fix: Setz den base-Pfad in vite.config.ts passend zu dem Ort, an dem die App liegt. Für eine Root-Domain ist das "/"; für eine GitHub-Pages-Projektseite ist es "/your-repo/":

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

Bau danach neu. Wenn du am Root einer Domain oder auf einer *.pages.dev- / *.netlify.app-Subdomain hostest, stimmt das Standard-"/" bereits – deshalb vermeidest du dieses Problem komplett, wenn du auf Cloudflare Pages oder Netlify deployst.

3. "API key is undefined" oder die KI-Funktionen tun einfach nichts

Die App lädt, aber alles, was Gemini aufruft, schlägt fehl. Zwei Fälle:

Die Umgebungsvariable ist beim Hoster nicht gesetzt. Trag sie in den Einstellungen des Hosters ein – bei Netlify unter Site settings, dann Environment variables, bei Cloudflare Pages unter Settings, dann Environment variables – mit genau dem Namen, den der Code erwartet, und deploye dann neu.

Die Variable ist gesetzt, aber der Wert ist ein Secret, das nicht mit ausgeliefert werden sollte. Ein Key, der ins Frontend-JavaScript gebündelt ist, kann von jedem gelesen werden, der die Seite öffnet. Für eine private Demo mag das in Ordnung sein; für alles Öffentliche schiebst du den Gemini-Aufruf hinter eine kleine serverlose Funktion (Netlify Functions, Cloudflare Workers), damit der Key auf dem Server bleibt und nie den Browser erreicht.

Nicht sicher, ob dein Build gerade dabei ist, einen Key preiszugeben? React2Static durchsucht das Projekt vor dem Download nach offengelegten Secrets und markiert sie, sodass du es merkst, bevor die App live ist, statt danach.

4. Die Startseite funktioniert, aber beim Neuladen anderer Seiten kommt ein 404

Deine App nutzt clientseitiges Routing (React Router und Ähnliches). Der erste Besuch klappt, weil er bei index.html startet; wenn du /about neu lädst, sucht der Hoster nach einer echten Datei unter /about, findet keine und meldet einen 404.

Fix: Sag dem Hoster, dass er bei unbekannten Pfaden index.html ausliefern soll.

Netlify – füg dem deployten Ordner eine _redirects-Datei hinzu:

/*    /index.html   200

Cloudflare Pages – liefert standardmäßig index.html für unbekannte Single-Page-App-Routen aus; falls bei dir nicht, füg dieselbe _redirects-Regel hinzu.

GitHub Pages – hat keinen solchen Fallback. Stell die App entweder auf Hash-Routing um oder kopiere index.html nach 404.html.

Tipp: Manche AI-Studio-Apps kommen schon mit HashRouter (URLs enthalten ein #), was dieses Problem komplett vermeidet.

Der sicherere Standardweg: erst zu statischen Dateien exportieren

Drei dieser vier Fallen haben eine gemeinsame Ursache – es wurde Quellcode statt eines richtigen Builds ausgeliefert, oder er landete bei einem Hoster, der genau das Gegenteil erwartet hat. Wenn du erst zu statischen Dateien baust und diese dann bei einem Hoster deployst, der sie vom Root ausliefert, nimmst du dem Risiko schon im Vorfeld den größten Teil. Das ist der Ablauf in Eine Google-AI-Studio-App kostenlos deployen (ohne Cloud Run). Wenn dir das neu ist, starte die App erst lokal, damit du weißt, dass sie funktioniert, bevor sie öffentlich wird.

FAQ

Warum bleibt meine Google-AI-Studio-App nach dem Deploy leer?

Meistens weil der Quellordner statt des gebauten dist/-Ordners hochgeladen wurde, oder weil der Basispfad des Builds nicht zu dem Ort passt, an dem er gehostet wird. Fehlende Umgebungsvariablen und Single-Page-App-Routing sind die beiden anderen häufigen Ursachen.

Warum bekomme ich 404-Fehler für meine JavaScript-Dateien?

Der Basispfad passt nicht zu dem Ort, an dem die App gehostet wird. Setz base in vite.config.ts auf "/" für eine Root-Domain oder auf "/your-repo/" für eine GitHub-Pages-Projektseite und bau danach neu.

Warum gibt ein Reload der Seite einen 404?

clientseitiges Routing braucht einen Hoster, der bei unbekannten Pfaden auf index.html zurückfällt. Füg bei Netlify oder Cloudflare Pages eine _redirects-Regel hinzu, oder nutz bei GitHub Pages Hash-Routing.

Ist es sicher, meinen Gemini-API-Key in die deployte App zu packen?

Nein – ein Key im Frontend-Code ist für jeden sichtbar, der die Seite öffnet. Ruf Gemini für alles Öffentliche über eine serverlose Funktion auf, damit der Key auf dem Server bleibt.