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

Matcher: Equals
URL: /alte-seite
Ziel: /neue-seite

Trifft zu: /alte-seite
Trifft nicht zu: /alte-seite/, /alte-seite?query=1, /alte-seite-extra

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

Matcher: Matches Regex
URL: ^/blog/(\d+)
Ziel: /artikel/$1

Trifft zu: /blog/123 → /artikel/123
Trifft nicht zu: /BLOG/123 (Groß-/Kleinschreibung-sensitiv)

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

Matcher: Matches Regex Case-Insensitive
URL: ^/produkte/(.*)
Ziel: /shop/$1

Trifft zu: /produkte/artikel → /shop/artikel
Trifft auch zu: /PRODUKTE/artikel → /shop/artikel

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.

Position: 1
Matcher: Matches Regex
URL: ^/alter-bereich/(.*)\.html$
Ziel: /neuer-bereich/$1

Ergebnis:
/alter-bereich/ueber-uns.html → /neuer-bereich/ueber-uns
/alter-bereich/kontakt.html → /neuer-bereich/kontakt

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.

Position: 1
Matcher: Matches Regex
URL: ^/produkt/([0-9]+)$
Ziel: /produkt.php?id=$1

Ergebnis:
/produkt/12345 → /produkt.php?id=12345
(Saubere URL wird zur tatsächlichen Backend-URL umgeschrieben)

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.

Position: 1
Matcher: Matches Regex
URL: ^/([0-9]{4})/([0-9]{2})/(.*)$
Ziel: /posts/$1-$2-$3

Ergebnis:
/2024/03/mein-blog-post → /posts/2024-03-mein-blog-post
/2023/12/ein-anderer-post → /posts/2023-12-ein-anderer-post

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

Position 1: /exakt/spezifischer/pfad → /ziel1
Position 2: /spezifisch/* → /ziel2
Position 3: /* → /ziel3

2. Exakte Treffer vor Mustern

Position 1: = /spezial-seite → /neue-spezial
Position 2: ~ ^/spezial → /regulaer-spezial

3. Nachfolgende Regeln bedenken

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

Rewrite Rule: /alt/* → /neu/*
Page Rule: Match /neu/* (nicht /alt/*)

4. Ähnliche Muster zusammenfassen

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

❌ Weniger effizient (mehrere Regeln):
/alt-ueber-uns → /ueber-uns
/alt-kontakt → /kontakt
/alt-hilfe → /hilfe

✅ Effizienter (eine Regel):
^/alt-(.*)$ → /$1

Verwende Regex für Flexibilität:

❌ Mehrere spezifische Regeln:
/produkt-1 → /artikel/1
/produkt-2 → /artikel/2
...

✅ Eine flexible Regel:
^/produkt-([0-9]+)$ → /artikel/$1

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

Position 1: ~ ^/(.*)$ → /neu/$1
→ Schreibt ALLES um, andere Regeln treffen nie zu

✅ Spezifische Muster zuerst

Position 1: = /spezial → /neu-spezial
Position 2: ~ ^/blog/(.*)$ → /artikel/$1
Position 3: ~ ^/alt-(.*)$ → /$1

---

❌ Page Rules vergessen

Rewrite Rule: /alt-admin → /admin
Page Rule: Match /alt-admin/* → TRIFFT NIE ZU
Sollte matchen: /admin/*

✅ Page Rules matchen umgeschriebene URLs

Rewrite Rule: /alt-admin → /admin
Page Rule: Match /admin/* → Trifft nach Umschreibung zu

---

❌ Ungültiger Zielpfad

URL: ^/produkt/(.*)$
Ziel: /ungueltig/$2 (Capture-Group $2 existiert nicht)
→ Fehlerhafte Umschreibung

✅ Gültige Capture-Groups

URL: ^/produkt/(.*)$
Ziel: /artikel/$1 (verwendet Capture-Group $1)

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