Rewrite Rules

Rewrite Rules ermöglichen die Transformation eingehender URLs, bevor jegliche andere Verarbeitung stattfindet. Sie funktionieren wie nginx Rewrite-Regeln 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 Conditional Rules, wodurch URL-Transformationen stattfinden, bevor Konfigurationsregeln die URL auswerten.

Wichtige Eigenschaften:

Werden als zweites in der Regelsequenz ausgeführt (nach Access Rules, vor 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

Der Rewrite-Regel-Editor: Name, Beschreibung, Übereinstimmungstyp, URI-Muster, Zielpfad und eine Live-Vorschau.

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 Conditional 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 Conditional Rules verwendet.

URL-Abgleich

Rewrite Rules gleichen URLs mit drei verschiedenen Matchern ab:

Die Auswahl „Übereinstimmungstyp“: Exakt, Regex und Regex ohne Beachtung der Groß-/Kleinschreibung.

Matcher

Exakt (=): Exakter Treffer

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

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

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

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

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

Regex · Groß-/Kleinschreibung egal (~*): Groß-/Kleinschreibung-ignorierender Regex

Matcher: Regex · Groß-/Kleinschreibung egal
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

Rewrite Rules verwenden wenn:

Legacy-URLs unterstützt werden müssen, während die Site umstrukturiert wird
saubere, SEO-freundliche URLs gewünscht sind (z. B. /produkt/123 statt /produkt.php?id=123)
eine Migration von einer anderen Plattform erfolgt und alte URL-Strukturen beibehalten werden müssen
URL-Normalisierung benötigt wird (z. B. Trailing-Slashes entfernen, URLs kleinschreiben)
URL-Transformationen vor der Auswertung anderer Regeln stattfinden sollen

Rewrite Rules treiben auch die On-the-fly-Bildverarbeitung von smoxy an – sie bilden saubere, öffentliche URLs auf die Verarbeitungspfade /_sx/img/... ab.

Anwendungsfälle & Beispiele

Beispiel 1: Legacy-URL-Unterstützung

Szenario: Die Site wurde von /alter-bereich/seite.html zu /neuer-bereich/seite umstrukturiert, alte Links müssen aber weiter unterstützt werden.

Position: 1
Matcher: Regulärer Ausdruck
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 der ursprüngliche Anfragekontext bleibt erhalten. Conditional Rules können dann Konfigurationen basierend auf der neuen URL anwenden.

Beispiel 2: Saubere URL-Struktur

Szenario: Die Anwendung verwendet Query-Parameter, saubere URLs für SEO sind aber gewünscht.

Position: 1
Matcher: Regulärer Ausdruck
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 das 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: Regulärer Ausdruck
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 Conditional Rules: Nach dem Umschreiben kann eine Conditional 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 die Anwendung erhält. Es muss sichergestellt sein, dass es ein gültiger Pfad ist, den die Anwendung verarbeiten kann.

Best Practices für die Regelreihenfolge

Da Rewrite Rules beim ersten Treffer stoppen, ist eine sorgfältige Anordnung wichtig. Wie die Rewrite-Reihenfolge in die Gesamtpipeline passt, ist unter Ausführung & Reihenfolge beschrieben.

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

Zu beachten: Conditional Rules werten gegen die umgeschriebene URL aus, nicht die originale:

Rewrite Rule: /alt/* -> /neu/*
Conditional Rule: Match /neu/* (nicht /alt/*)

4. Ähnliche Muster zusammenfassen

Regex einsetzen, 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

Regex für Flexibilität einsetzen:

Mehrere spezifische Regeln:

/produkt-1 -> /artikel/1
/produkt-2 -> /artikel/2
...

Eine flexible Regel:

^/produkt-([0-9]+)$ -> /artikel/$1

Eindeutigkeit

Jede Zone muss eindeutige haben:

Regelnamen – jede Regel muss einen eindeutigen Namen haben
URL-Muster – doppelte URL-Muster sind nicht zulässig

Beim Versuch, ein Duplikat zu erstellen, erscheint: "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

Conditional Rules vergessen

Rewrite Rule: /alt-admin -> /admin
Conditional Rule: Match /alt-admin/* -> TRIFFT NIE ZU
Sollte matchen: /admin/*

Conditional Rules matchen umgeschriebene URLs

Rewrite Rule: /alt-admin -> /admin
Conditional 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

Debug-Header aktivieren in der Zonen-Konfiguration
Testanfragen mit den originalen URLs durchführen
Response-Header prüfen um zu sehen, welche Regeln angewendet wurden und wie die URL transformiert wurde
Verifizieren, dass Conditional Rules die umgeschriebene URL matchen, nicht die originale

Rewrite Rules ​

Was sind Rewrite Rules? ​

Wie Rewrite Rules funktionieren ​

Positionsbasierte Auswertung ​

URL-Abgleich ​

Matcher ​

URL vs URI ​

Wann Rewrite Rules verwenden ​

Rewrite Rules verwenden wenn: ​

Anwendungsfälle & Beispiele ​

Beispiel 1: Legacy-URL-Unterstützung ​

Beispiel 2: Saubere URL-Struktur ​

Beispiel 3: Plattform-Migration ​

Zielpfad ​

Best Practices für die Regelreihenfolge ​

1. Spezifischste zuerst ​

2. Exakte Treffer vor Mustern ​

3. Nachfolgende Regeln bedenken ​

4. Ähnliche Muster zusammenfassen ​

Eindeutigkeit ​

Häufige Fehler ​

Rewrite Rules testen ​