Rewrite Rules

Rewrite Rules ermöglichen es dir, eingehende URLs zu transformieren, bevor jegliche andere Verarbeitung stattfindet. Sie funktionieren wie nginx Rewrites und ermöglichen URL-Normalisierung, Legacy-URL-Unterstützung und saubere URL-Strukturen.

Was sind Rewrite Rules?

Rewrite Rules modifizieren die Anfrage-URL basierend auf einem URL-Abgleich. Sie werden früh im Anfrageablauf ausgewertet, direkt nach Access Rules und vor Page Rules, wodurch URL-Transformationen stattfinden, bevor Konfigurationsregeln die URL auswerten.

Wichtige Eigenschaften:

  • Werden als zweites in der Regelsequenz ausgeführt (nach Access Rules, vor Page und Conditional Rules)

  • Transformieren URLs vor der Cache-Abfrage

  • nginx-artige URL-Umschreibung

  • Werden in Positionsreihenfolge ausgewertet (1, 2, 3...)

  • Stopp nach erstem Treffer – sobald eine Regel zutrifft, werden keine weiteren Rewrite Rules ausgewertet

Wie Rewrite Rules funktionieren

Rewrite Rules werden in aufsteigender Positionsreihenfolge (1 → 2 → 3...) für jede eingehende Anfrage ausgewertet. Wenn das URL-Muster einer Regel zutrifft, wird die URL zum Zielpfad umgeschrieben und die Auswertung stoppt.

Positionsbasierte Auswertung

Anfrage: /alter-pfad
    ↓
Rewrite Rule (Position 1) → Treffer /alter-pfad? → Umschreiben zu /neuer-pfad → STOPP
    ↓ (kein Treffer)
Rewrite Rule (Position 2) → Treffer? → Umschreiben → STOPP
    ↓ (kein Treffer)
Weiter zu Page Rules mit originaler oder umgeschriebener URL...

Wichtig: Sobald eine Rewrite Rule zutrifft, werden keine weiteren Rewrite Rules ausgewertet. Die umgeschriebene URL wird dann von allen nachfolgenden Regeln (Page Rules, Conditional Rules) verwendet.

URL-Abgleich

Rewrite Rules verwenden das gleiche URL-Abgleichsystem wie Page Rules. Du kannst URLs mit drei verschiedenen Matchern abgleichen:

Matcher

Equals (=): Exakter Treffer

Matches Regex (~): Groß-/Kleinschreibung-sensitiver Regex

Matches Regex Case-Insensitive (~*): Groß-/Kleinschreibung-ignorierender Regex

URL vs URI

  • URL: Die vollständige Webadresse inklusive Protokoll und Domain

    • Beispiel: https://www.beispiel.de/kategorie/daten.html

  • URI: Nur der Pfad ohne Domain oder Protokoll

    • Beispiel: /kategorie/daten.html

Rewrite Rules arbeiten mit URIs (nur der Pfad).

Wann Rewrite Rules verwenden

Verwende Rewrite Rules wenn:

  • ✅ Du Legacy-URLs unterstützen musst, während du deine Website umstrukturierst

  • ✅ Du saubere, SEO-freundliche URLs möchtest (z.B. /produkt/123 statt /produkt.php?id=123)

  • ✅ Du von einer anderen Plattform migrierst und alte URL-Strukturen beibehalten musst

  • ✅ Du URL-Normalisierung benötigst (z.B. Trailing-Slashes entfernen, URLs kleinschreiben)

  • ✅ URL-Transformationen vor der Auswertung anderer Regeln stattfinden sollen

Anwendungsfälle & Beispiele

Beispiel 1: Legacy-URL-Unterstützung

Szenario: Du hast deine Website von /alter-bereich/seite.html zu /neuer-bereich/seite umstrukturiert, musst aber alte Links unterstützen.

Warum umschreiben statt weiterleiten? Umschreibungen sind transparent – der Benutzer sieht keine URL-Änderung, und du behältst den ursprünglichen Anfragekontext. Page Rules können dann Konfigurationen basierend auf der neuen URL anwenden.

Beispiel 2: Saubere URL-Struktur

Szenario: Deine Anwendung verwendet Query-Parameter, aber du möchtest saubere URLs für SEO.

Warum das funktioniert: Benutzer und Suchmaschinen sehen saubere URLs (/produkt/12345), aber dein Backend erhält das Query-Parameter-Format, das es erwartet.

Beispiel 3: Plattform-Migration

Szenario: Migration von WordPress zu einer neuen Plattform, wobei alte Post-URLs unterstützt werden müssen.

Kombiniert mit Page Rules: Nach dem Umschreiben kann eine Page Rule, die /posts/* matched, spezifische Caching- oder Optimierungseinstellungen anwenden.

Zielpfad

Der Zielpfad ist das Ziel, zu dem die URL umgeschrieben wird. Er kann sein:

  • Statischer Pfad: /neuer-ort

  • Mit Capture-Groups: /bereich/$1 (verwendet Regex-Capture-Groups aus dem URL-Muster)

  • Mehrere Captures: /kategorie/$1/artikel/$2

Wichtig: Der Zielpfad ist der tatsächliche Backend-Pfad, den deine Anwendung erhält. Stelle sicher, dass es ein gültiger Pfad ist, den deine Anwendung verarbeiten kann.

Best Practices für die Regelreihenfolge

Da Rewrite Rules beim ersten Treffer stoppen, ordne sie sorgfältig an:

1. Spezifischste zuerst

2. Exakte Treffer vor Mustern

3. Nachfolgende Regeln bedenken

Denke daran, dass Page Rules und Conditional Rules gegen die umgeschriebene URL auswerten, nicht die originale:

4. Ähnliche Muster zusammenfassen

Verwende Regex, um mehrere Fälle effizient zu behandeln:

Verwende Regex für Flexibilität:

Eindeutigkeit

Jede Website muss eindeutige haben:

  • Regelnamen – jede Regel muss einen eindeutigen Namen haben

  • URL-Muster – du kannst keine doppelten URL-Muster haben

Wenn du versuchst, ein Duplikat zu erstellen, siehst du: "Name existiert bereits" oder "Gleicher Matcher existiert."

Häufige Fehler

❌ Catch-all-Umschreibung auf Position 1

✅ Spezifische Muster zuerst

❌ Page Rules vergessen

✅ Page Rules matchen umgeschriebene URLs

❌ Ungültiger Zielpfad

✅ Gültige Capture-Groups

Rewrite Rules testen

  1. Aktiviere Debug-Header in deiner Website-Konfiguration

  2. Führe Testanfragen mit den originalen URLs durch

  3. Prüfe die Response-Header um zu sehen, welche Regeln angewendet wurden und wie die URL wurde

  4. Verifiziere, dass Page Rules die umgeschriebene URL matchen, nicht die originale

Last updated

Was this helpful?