Cloudflare-Caching und X-Inertia: Warum dein Laravel-Projekt falsche Fehlerseiten anzeigt

Ein scheinbar harmloser Klick auf das Logo einer Laravel-Anwendung mit Inertia endete in einem frustrierenden Fehler: Die Startseite wurde innerhalb des Inertia-Error-Modalfensters angezeigt – obwohl der Server eine HTTP-200-Antwort zurückgab. Doch wie konnte es dazu kommen? Der Grund lag in einer unglücklichen Kombination aus Cloudflare-Caching, Inertia-Serververhalten und falsch konfigurierten Cache-Regeln.

Wie Cloudflare und Inertia zusammenarbeiten – und warum es schiefging

Inertia.js ist ein modernes Framework, das serverseitiges Rendering mit clientseitigem Routing verbindet. Bei einer typischen Anfrage sendet der Server entweder reines HTML (für Erstbesucher) oder ein JSON-Objekt (für AJAX-Abfragen durch Inertia). Beide Antworten werden jedoch unter derselben URL ausgeliefert. Entwickler können Inertia-Seiten für das Edge-Caching von Cloudflare optimieren, indem sie den Header s-maxage verwenden.

Doch hier lag der Haken: Cloudflare ignoriert den Header Vary: X-Inertia standardmäßig. Dieser Header teilt dem Cache mit, dass die Antwort je nach Vorhandensein des X-Inertia-Flags variieren muss. Das Ergebnis? Der Edge-Cache lieferte HTML an eine AJAX-Anfrage, die eigentlich ein JSON-Objekt erwartet hatte. Selbst eine korrekte no-store-Direktive für JSON-Antworten konnte dies nicht verhindern, da die Fehlentscheidung bereits während der Cache-Speicherung getroffen wurde – nicht erst beim Abruf.

Ein praktischer Test: So prüfst du dein eigenes Inertia-Projekt

Um zu überprüfen, ob dein eigenes Projekt betroffen ist, kannst du einen einfachen curl-Befehl nutzen. Führe folgende Schritte aus:

curl -I -H "X-Inertia: true" 

Ein kritisches Indiz für das Problem ist ein cf-cache-status: HIT bei einer Anfrage mit X-Inertia: true. Dies bedeutet, dass der Edge-Cache trotz des Flags eine gecachte HTML-Antwort ausgeliefert hat. Ein weiterer Test besteht darin, die Antwort headers zu prüfen:

• Fehlt der Vary: X-Inertia-Header?
• Wird s-maxage für die HTML-Antwort gesetzt?
• Liefert der Cache bei X-Inertia: true trotzdem HTML zurück?

Falls ja, ist dein Projekt von diesem Verhalten betroffen.

Die Lösung: Einfache Anpassungen für zuverlässiges Caching

Die gute Nachricht: Die Behebung des Problems erfordert nur minimale Änderungen. Der Autor des Originalartikels beschreibt eine Einzeiler-Lösung, die Vary: X-Inertia explizit im Cache-Key berücksichtigt. Zusätzlich empfiehlt er die Nutzung einer Cloudflare-Cache-Regel, um das Edge-Caching für Inertia-Projekte sicher zu gestalten – vorausgesetzt, du hast Zugriff auf deine eigene Cloudflare-Zone.

Ein Beispiel für die Cache-Regel könnte so aussehen:

Cache-Regel: "Inertia HTML"
Anwendungsfall: URL-Pfad ist "/dashboard*"
Cache-Verhalten: Cache-Einstellungen anpassen
Cache-Key: "{uri} - {header X-Inertia}"

Durch diese Regel wird sichergestellt, dass HTML- und JSON-Antworten unter derselben URL nicht vermischt werden. Der Cache-Key berücksichtigt nun das X-Inertia-Header, sodass jede Antwortart separat behandelt wird.

Fazit: Performance behalten, ohne Fehler zu riskieren

Cloudflare Edge-Caching kann die Ladezeiten von Inertia-Anwendungen deutlich verbessern – doch ohne die richtige Konfiguration führt es zu unerwarteten Fehlern. Entwickler sollten sicherstellen, dass Cache-Regeln den Vary: X-Inertia-Header respektieren, um falsche Antworten zu vermeiden. Ein kurzer Test mit curl hilft, potenzielle Probleme frühzeitig zu erkennen. Durch die Kombination aus Cache-Regeln und Header-Anpassungen lässt sich die Performance optimieren, ohne die Funktionalität der Anwendung zu gefährden.