So behebst du eine weiße Seite in deiner Web-App

Eine weiße Seite bedeutet fast immer eines von zwei Dingen: Das JavaScript der App ist abgestürzt, bevor etwas gezeichnet wurde, oder das JavaScript wurde gar nicht geladen. Öffne die Browser-Konsole (Rechtsklick → Untersuchen → Konsole), lies den ersten roten Fehler und prüfe dann im Tab Netzwerk, welche Dateien nicht geladen werden konnten. Die meisten Ursachen sind eine fehlende Umgebungsvariable, ein falscher Basispfad, ein Build, der nicht fertig wurde, oder ein Absturz in einer einzelnen Komponente.

Dieser Leitfaden behandelt Single-Page-Apps, die mit React, Vue oder ähnlichen Frameworks gebaut wurden (auch Apps von KI-Buildern), denn dort treten weiße Seiten am häufigsten auf.

Warum die Seite weiß ist

Eine moderne Single-Page-App (SPA) schickt dem Browser eine nahezu leere HTML-Datei, etwa so:

<body>
  <div id="root"></div>
  <script type="module" src="/assets/index-a1b2c3.js"></script>
</body>

Das JavaScript baut dann die ganze Seite in diesem leeren div auf. Lädt das Skript nicht oder wirft es einen Fehler, bevor es rendert, bleibt das div leer, und du siehst Weiß. Die Seite ist nicht auf sichtbare Weise „kaputt“; sie wurde nur nie gezeichnet.

Deshalb beginnt die Fehlersuche immer in den Entwicklertools, nicht auf der Seite selbst.

Schritt 1: Die Konsole lesen

Öffne die Entwicklertools: Rechtsklick auf die Seite und Untersuchen wählen oder F12 drücken (Cmd+Option+I auf dem Mac). Wechsle zum Tab Konsole und lade die Seite neu.

Schau dir den ersten roten Fehler an; spätere sind oft Nebenwirkungen. Was er sagt, verrät die Ursache:

Kopiere den vollständigen Fehlertext einschließlich Dateiname und Zeilennummer. Wenn du einen KI-Builder nutzt, füge ihn direkt in den Chat ein.

Schritt 2: Prüfen, ob die Dateien geladen wurden

Öffne den Tab Netzwerk, aktiviere Cache deaktivieren und lade neu. Schau dir die Anfragen für .js- und .css-Dateien an.

• Status 404 bei einer JavaScript-Datei: Die Seite fordert eine Datei an, die auf dem Server nicht existiert.
• Status 200, aber der Typ ist text/html: Der Server hat eine Seite geliefert (oft index.html selbst, wegen eines SPA-Fallbacks) statt des Skripts. Die Ursache ist dieselbe: Die Datei liegt nicht dort, wo die Seite sie erwartet.

Übliche Gründe:

Falscher Basispfad. Wird die App aus einem Unterordner ausgeliefert, etwa example.com/app/, wurde sie aber so gebaut, dass sie Dateien unter /assets/... lädt, gehen alle Skript-Anfragen ins Leere. In Vite ist das die Option base in vite.config; in Create React App das Feld homepage; in Next.js basePath. Er muss dem Ort entsprechen, an dem die App tatsächlich ausgeliefert wird.

Veraltete index.html. Build-Tools geben Dateien Namen mit einem Inhalts-Hash, etwa index-a1b2c3.js. Nach einem neuen Deployment ist die alte Datei verschwunden. Hat ein Browser oder CDN noch die alte index.html zwischengespeichert, fragt sie nach der alten Datei und bekommt nichts. Ein hartes Neuladen (Cmd+Shift+R oder Strg+Umschalt+R) bestätigt das. Die langfristige Lösung: index.html mit einem kurzen oder keinem Cache-Header ausliefern, während die gehashten Dateien lange gecacht werden.

Der Build wurde nicht fertig oder nicht deployt. Ist der Build fehlgeschlagen, liefert der Host vielleicht einen alten oder leeren Ausgabeordner. Prüfe das Build-Log auf Fehler.

Der falsche Ordner wird veröffentlicht. Der Host muss das Build-Ergebnis ausliefern (meist dist oder build), nicht den Quellordner des Projekts. Wird der Quellordner ausgeliefert, bekommst du eine index.html, die auf /src/main.tsx zeigt, was Browser nicht ausführen können.

Schritt 3: Umgebungsvariablen prüfen

Frontend-Apps lesen Einstellungen wie eine API-URL oder einen öffentlichen Schlüssel oft zur Build-Zeit. Fehlt eine Variable im Live-Build, wirft Code wie createClient(undefined, undefined) sofort einen Fehler, und die Seite wird weiß.

Wichtig zu wissen:

• In Vite sind nur Variablen mit dem Präfix VITE_ im Browser-Code verfügbar und werden als import.meta.env.VITE_NAME gelesen. In Create React App ist es REACT_APP_; in Next.js NEXT_PUBLIC_.
• Diese Werte werden beim Bauen fest eingebettet. Eine Variable nach dem Build hinzuzufügen bewirkt nichts, bis du neu baust und deployst.
• Die Vorschau oder dein lokaler Rechner hat möglicherweise eine .env-Datei, die der Produktions-Build nicht hat. Setze dieselben Variablen auf dem Host.
• Alles mit diesen Präfixen landet im öffentlichen JavaScript. Trage dort nur öffentliche Werte ein, niemals geheime Schlüssel.

Ein schneller Test: Suche in der Konsolenmeldung nach undefined in der Nähe eines Einstellungsnamens, oder frag:

Die veröffentlichte App zeigt eine leere Seite. Liste jede Umgebungsvariable auf, die das Frontend liest, prüfe, welche im Live-Build fehlen oder leer sind, und sorge dafür, dass die App bei einer fehlenden Variable eine klare Fehlermeldung statt einer leeren Seite anzeigt.

Schritt 4: Den Absturz beheben

Zeigt die Konsole einen normalen JavaScript-Fehler, ist der Code beim Rendern abgestürzt. Typische Ursachen in KI-gebauten Apps:

• Daten noch nicht geladen. Eine Komponente liest user.name, bevor user angekommen ist. Die Lösung ist ein Ladezustand oder optionales Verketten (user?.name).
• Leere Daten. Ein neues Konto hat keine Einträge, und der Code setzt voraus, dass die Liste mindestens ein Element hat.
• Unerwartete Datenform. Eine API hat ein Fehlerobjekt statt der erwarteten Liste zurückgegeben.
• Ein fehlender Import, nachdem eine Datei umbenannt oder verschoben wurde.
• Eine browserspezifische API beim serverseitigen Rendern, etwa window oder localStorage in einer Next.js-Server-Komponente.

Gib der KI den vollständigen Fehler, die Seite und das Konto, mit dem du angemeldet warst:

Die Dashboard-Seite ist für neue Nutzer leer. Konsole: TypeError: Cannot read properties of undefined (reading 'map') bei ProjectList.tsx:18. Für mein Konto, das Projekte hat, funktioniert es. Behebe es so, dass ein leeres Konto „Noch keine Projekte“ anzeigt, und prüfe ein neues Konto in der Vorschau.

Schritt 5: Eine Error Boundary hinzufügen

In React kann eine einzige abstürzende Komponente die ganze App aushängen, deshalb führt ein kleiner Fehler zu einer komplett leeren Seite. Eine Error Boundary ist eine Komponente, die Renderfehler darunter abfängt und stattdessen eine Fallback-Ansicht zeigt.

Füge eine Error Boundary um die Hauptrouten hinzu, die „Etwas ist schiefgelaufen“ mit einer Schaltfläche „Neu laden“ anzeigt und den Fehler in der Konsole protokolliert. Halte Header und Navigation außerhalb, damit sie weiterhin angezeigt werden.

Sie behebt den Fehler nicht, aber Besucher sehen eine Meldung statt eines leeren Bildschirms, und du siehst, wo es kaputtging.

Schritt 6: Kein Fehler, aber trotzdem leer

Wenn die Konsole sauber ist und die Skripte laden:

• Prüfe den Tab Elemente. Steht Inhalt in <div id="root">? Dann rendert die App, aber das Ergebnis ist unsichtbar: weißer Text auf Weiß, opacity: 0, display: none oder ein Vollbild-Element, das alles überdeckt.
• Prüfe den Router. Passt keine Route zur aktuellen URL und gibt es keine „Nicht gefunden“-Route, rendern manche Router gar nichts. Füge eine Catch-all-Route hinzu, die eine 404-Seite zeigt.
• Prüfe den Einhängepunkt. Der Code muss in ein Element einhängen, das existiert. Hat index.html id="app", der Code sucht aber root, erscheint nichts (und React protokolliert meist einen Fehler).
• Prüfe eine Browser-Erweiterung. Probiere ein privates Fenster. Werbeblocker blockieren gelegentlich Skripte mit Namen wie analytics oder ads.

Nur leer nach dem Neuladen einer Seite?

Funktioniert die Startseite, zeigt das Neuladen von /dashboard aber eine leere Seite oder einen 404, weiß der Server nicht, dass er für App-Routen index.html ausliefern soll. Das ist ein Problem mit dem Routing-Fallback, das in wie du 404-Fehler nach dem Deployment behebst behandelt wird.

Häufige Fehler

• Den letzten statt des ersten Fehlers lesen. Die erste rote Zeile ist meist die Ursache.
• Umgebungsvariablen setzen, ohne neu zu bauen. Frontend-Variablen sind zur Build-Zeit festgelegt.
• Nur mit dem eigenen Konto testen. Abstürze bei leeren Konten gehören zu den häufigsten Ursachen weißer Seiten.
• Annehmen, das Deployment hat funktioniert. Prüfe das Build-Log, bevor du den Code debuggst.
• Den Browser-Cache für alles verantwortlich machen. Ein hartes Neuladen schließt ihn in Sekunden aus; ist die Seite dann noch leer, liegt es an etwas anderem.

Weiße Seiten in Mythex

Ist die Vorschau leer, prüfe zuerst, ob die App läuft (öffne Code → Terminal), und lass dann Mythex den richtigen Server starten, klicke Aktualisieren in der Vorschau-Leiste oder nutze /fix. Bei einer leeren veröffentlichten URL empfiehlt die Dokumentation, eine Minute zu warten und hart neu zu laden, zu prüfen, ob Umgebungsvariablen und Datenbank vor dem Veröffentlichen eingerichtet waren, und dein Hosting-Kontingent zu prüfen. Denke daran, dass eine veröffentlichte App ein Snapshot ist: Nach einer Korrektur musst du erneut veröffentlichen. Hat eine Änderung das Problem verursacht, setzt Zu diesem Punkt zurückkehren an der letzten guten Antwort das Projekt zurück. Siehe Fehlerbehebung und Fehlerbehebung bei der Veröffentlichung in der Dokumentation sowie unseren allgemeinen Leitfaden zum Debuggen einer KI-gebauten App.

Checkliste für weiße Seiten

• Ersten roten Fehler in der Konsole gelesen
• Im Tab Netzwerk geprüft, ob .js-/.css-Dateien 404 liefern oder HTML zurückgeben
• Basispfad stimmt mit dem Ort überein, an dem die App ausgeliefert wird
• Build fertig, und der Build-Ausgabeordner ist das, was veröffentlicht wird
• Alle Frontend-Umgebungsvariablen im Live-Build gesetzt, dann neu gebaut
• Absturz behoben, auch für leere und neue Konten
• Error Boundary vorhanden, damit künftige Abstürze eine Meldung zeigen
• Catch-all-Route für unbekannte URLs
• Nach hartem Neuladen und in einem privaten Fenster getestet

Fragen