NGINX Rewrite-Regeln

NGINX Rewrite-Regeln ermöglichen es, eine von einem Client angeforderte URL vollständig oder teilweise zu verändern. Ein Grund für eine URL-Änderung besteht darin, Clients darüber zu informieren, dass sich eine angeforderte Ressource jetzt an einer anderen Adresse befindet. Zusätzlich lassen sich Rewrite-Regeln einsetzen, um zu steuern, wie NGINX eingehende Anfragen verarbeitet.

Die NGINX-Direktiven return und rewrite können beide verwendet werden, um URLs anzupassen. Obwohl sich mit beiden Direktiven Weiterleitungen umsetzen lassen, unterscheiden sie sich in ihrer Funktionsweise.

• Die Direktive return ist die einfachste und effizienteste Möglichkeit, Weiterleitungen umzusetzen.
• Die Direktive rewrite bietet mehr Flexibilität, wenn URLs transformiert oder anhand von Mustern ausgewertet werden müssen.

In diesem Tutorial wird erklärt, wie sich die NGINX-Direktiven return und rewrite zum Weiterleiten, Ändern und Umschreiben von URLs verwenden lassen.

Wichtige Erkenntnisse:

• Verwende return für einfache Weiterleitungen, da diese Variante effizienter ist. rewrite eignet sich dagegen für URL-Transformationen auf Basis regulärer Ausdrücke oder für Musterabgleiche.
• Das Flag break beendet die Rewrite-Verarbeitung und verarbeitet die Anfrage innerhalb des aktuellen Location-Blocks weiter, ohne andere Location-Blöcke erneut zu prüfen.
• Das Flag last startet mit der umgeschriebenen URI eine neue Suche nach einem passenden Location-Block. Eine fehlerhafte Konfiguration kann zu einer Endlosschleife führen, wenn die neue URI erneut eine passende Rewrite-Regel auslöst.
• Verwende permanent mit HTTP-301-Weiterleitungen bei SEO-relevanten Migrationen, bei denen Rankingsignale auf die neue URL übertragen werden sollen. redirect mit HTTP 302 ist für vorübergehende Änderungen gedacht, bei denen keine dauerhafte Übertragung von SEO-Signalen beabsichtigt ist.
• Capture Groups in regulären Ausdrücken werden mit ( ) definiert und erzeugen Variablen wie $1 und $2. Dadurch kann eine einzelne Rewrite-Regel mehrere dynamische URLs verarbeiten.
• NGINX verarbeitet zunächst Rewrite-Direktiven im Server-Kontext, wählt anschließend einen passenden Location-Block und verarbeitet danach die dort definierten Rewrite-Direktiven. Dieses Verständnis hilft dabei, unerwartetes Verhalten zu vermeiden.
• Verwende proxy_redirect, wenn NGINX als Reverse Proxy eingesetzt wird und die von Backend-Servern zurückgegebenen Header Location oder Refresh angepasst werden müssen.
• Die Direktive map verwendet Hash-Tabellen für Zuordnungen und kann deshalb effizienter sein als eine große Anzahl nacheinander ausgewerteter Rewrite-Regeln.

NGINX Return-Direktive

Die Direktive return gehört zu den einfachsten und übersichtlichsten Möglichkeiten, eine URL weiterzuleiten. Sie muss innerhalb eines server– oder location-Kontexts definiert werden und enthält den benötigten HTTP-Statuscode sowie die Ziel-URL.

1. NGINX Return-Direktive im Server-Kontext

Die Verwendung von return im Server-Kontext ist besonders hilfreich, wenn eine Website auf eine andere Domain umgezogen ist und alle URLs der bisherigen Domain auf die neue Domain weitergeleitet werden sollen. Sie kann außerdem zur URL-Kanonisierung eingesetzt werden, beispielsweise um Besucher konsequent auf die www– oder die nicht-www-Variante einer Domain umzuleiten.

server {
        listen 80;
        server_name www.olddomain.com;
        return 301 $scheme://www.newdomain.com$request_uri;
}

In dieser Server-Konfiguration werden Anfragen an www.olddomain.com auf www.newdomain.com weitergeleitet. Sobald NGINX eine Anfrage für www.olddomain.com erhält, wird die weitere Verarbeitung beendet und eine HTTP-301-Antwort mit der neuen Ziel-URL an den Client zurückgegeben.

Im gezeigten return-Beispiel werden zwei Variablen verwendet: $scheme und $request_uri.

• $scheme steht für das verwendete URL-Protokoll, beispielsweise HTTP oder HTTPS.
• $request_uri enthält die vollständige Request-URI einschließlich vorhandener Query-Parameter.

2. Return-Direktive im Location-Kontext

In manchen Fällen sollen nicht komplette Domains, sondern nur einzelne Seiten weitergeleitet werden. Eine return-Direktive innerhalb eines Location-Blocks ermöglicht es, eine bestimmte Seite auf eine andere Adresse umzuleiten.

location = /tutorial/learning-nginx {
     return 301 $scheme://example.com/nginx/understanding-nginx;
}

In diesem Beispiel leitet NGINX die Anfrage auf https://example.com/nginx/understanding-nginx/ weiter, sobald die angeforderte URI exakt mit /tutorial/learning-nginx übereinstimmt.

Alternativ können auch sämtliche Anfragen unterhalb eines bestimmten Pfads an ein neues Ziel weitergeleitet werden:

location /tutorial {
     return 301 $scheme://example.com/articles;
}

NGINX Rewrite-Direktive

Mit der NGINX-Direktive rewrite steht eine weitere Möglichkeit zur Verfügung, URLs zu verändern. Genau wie return kann auch rewrite sowohl im Server- als auch im Location-Kontext definiert werden.

Die Direktive rewrite ist besonders nützlich, wenn URLs mithilfe regulärer Ausdrücke erkannt und umgewandelt werden müssen. Im Unterschied zu return verändert sie die Request-URI und kann die Verarbeitung abhängig vom verwendeten Flag anschließend fortsetzen.

Die Syntax der rewrite-Direktive lautet:

rewrite regex replacement [flag];

• regex: Ein PCRE-basierter regulärer Ausdruck, der mit der Request-URI und nicht mit der vollständigen URL verglichen wird.
• replacement: Die URI oder URL, durch die die übereinstimmende Anfrage ersetzt wird.
• flag: Legt fest, wie NGINX nach der Umschreibung weiterarbeitet.

Hinweis: Für einfache Weiterleitungen ist return in der Regel besser geeignet als rewrite, da die Konfiguration klarer und effizienter ist.

Verarbeitungsreihenfolge von NGINX Rewrite-Regeln

NGINX wertet Rewrite-Regeln in einer festgelegten Reihenfolge aus:

1. Zunächst werden Rewrite-Direktiven im Server-Kontext verarbeitet.
2. Danach ermittelt NGINX den am besten passenden Location-Block.
3. Anschließend werden die Rewrite-Direktiven innerhalb dieses Location-Blocks ausgeführt.
4. Wird das Flag last verwendet, führt NGINX eine neue Location-Suche durch.

Diese Reihenfolge zu kennen ist besonders wichtig, wenn mehrere Rewrite-Regeln gleichzeitig verwendet werden, da sich dadurch unerwartete Ergebnisse vermeiden lassen.

Beispiele für die NGINX Rewrite-Direktive

Die folgenden Beispiele zeigen verschiedene typische Rewrite-Szenarien. Den Anfang macht eine einfache Umschreibung einer statischen Seite auf eine andere URL.

1. Statische Seite umschreiben

Angenommen, die URL https://example.com/nginx-tutorial soll intern auf https://example.com/somePage.html aufgelöst werden. Die entsprechende Rewrite-Direktive kann im folgenden Location-Block definiert werden.

server {
          ...
          ...
          location = /nginx-tutorial 
          { 
            rewrite ^/nginx-tutorial$ /somePage.html break; 
          }
          ...
          ...
}

Erklärung:

• Die Direktive location = /nginx-tutorial bedeutet, dass dieser Location-Block ausschließlich bei einer exakten Anfrage nach /nginx-tutorial verwendet wird.
• NGINX vergleicht die angeforderte URI mit dem Muster ^/nginx-tutorial$.
• Die Zeichen ^ und $ besitzen innerhalb des Musters eine besondere Bedeutung.
• ^ kennzeichnet den Anfang der Zeichenfolge, die abgeglichen werden soll.
• $ kennzeichnet das Ende der Zeichenfolge.
• Stimmt die angeforderte URI vollständig mit dem Muster überein, wird somePage.html als Ersatz verwendet.
• Da die Rewrite-Regel mit break endet, wird die weitere Rewrite-Verarbeitung beendet und die neue URI nicht noch einmal an einen anderen Location-Block übergeben.

2. Dynamische Seite umschreiben

Betrachte eine dynamische URL wie https://www.example.com/user.php?id=11, bei der id=11 eine dynamische Benutzer-ID darstellt. Stattdessen soll eine URL wie https://www.example.com/user/11 verwendet werden. Für jeden Benutzer eine eigene Rewrite-Regel zu erstellen, wäre bei vielen Benutzern unpraktisch. Stattdessen lässt sich ein Teil der URL in einer Variablen erfassen, sodass eine einzige Rewrite-Regel alle passenden dynamischen Seiten verarbeiten kann.

server {
          ...
          ...
          location /user 
          { 
            rewrite ^/user/([0-9]+)/?$ /user.php?id=$1 break; 
          }
          ...
          ...
}

Erklärung:

• Die Direktive location /user weist NGINX an, diesen Location-Block für URLs zu verwenden, die mit dem Präfix /user beginnen.
• NGINX vergleicht die angeforderte URI mit dem Muster ^/user/([0-9]+)/?$.
• Der Ausdruck [0-9]+ steht für eine oder mehrere Ziffern zwischen 0 und 9. Das Zeichen + bedeutet, dass das unmittelbar davorstehende Muster mindestens einmal und auch mehrfach vorkommen darf. Ohne + würden lediglich einzelne Werte wie 5 oder 8 erkannt, nicht jedoch Zahlen wie 25 oder 44.
• Die Klammern ( ) erzeugen eine Capture Group beziehungsweise Backreference. Die Variable $1 in user.php?id=$1 verweist auf den durch diese Gruppe erfassten Wert.

Wird beispielsweise https://www.example.com/user/24 aufgerufen, entspricht die Benutzer-ID 24 dem erfassten Bereich. Daraus ergibt sich die Umschreibung auf https://www.example.com/user.php?id=24.

3. Erweiterte URL-Umschreibung

Ein weiteres Beispiel ist die Zuordnung von https://www.example.com/user.php?user_name=john zu https://www.example.com/user/login/john. Anders als im vorherigen Beispiel besteht der dynamische Teil user_name=john hier aus alphabetischen Zeichen. Die passende Rewrite-Regel sieht folgendermaßen aus:

server {
          ...
          ...
          location /user/login 
            { 
                rewrite ^/user/login/([a-z]+)/?$ /user.php?user_name=$1 break;           
            }
          ...
          ...
  }

Erklärung:

• Die Direktive location /user/login legt fest, dass NGINX URLs verarbeitet, die mit dem Präfix /user/login beginnen.
• NGINX vergleicht die angeforderte URI mit ^/user/login/([a-z]+)/?$.
• Der Ausdruck [a-z]+ entspricht einem oder mehreren Kleinbuchstaben von a bis z. Das Zeichen + erlaubt mehrere aufeinanderfolgende Zeichen. Ohne dieses Zeichen könnten lediglich einzelne Buchstaben wie a oder c erkannt werden, nicht jedoch Werte wie john oder doe.
• Die Klammern ( ) definieren eine Capture Group. Die Variable $1 in user.php?user_name=$1 enthält den innerhalb dieser Gruppe erfassten Wert.

Bei einer Eingabe wie https://www.example.com/user/login/john wird der Wert john erfasst. Daraus entsteht die Umschreibung auf https://www.example.com/user.php?user_name=john.

4. URLs mit mehreren Backreferences umschreiben

Dieses Beispiel zeigt, wie sich mehrere Backreferences innerhalb einer Rewrite-Regel einsetzen lassen. Angenommen, die eingehende URL lautet https://example.com/tutorial/linux/wordpress/file1 und soll zu https://example.com/tutorial/linux/cms/file1.php umgeschrieben werden. Der ursprüngliche Pfad beginnt mit /tutorial, während das spätere Segment wordpress durch cms ersetzt werden soll. Zusätzlich muss die Dateiendung .php an den Dateinamen angehängt werden. Die entsprechende Regel lautet:

server {
          ...
          ...
          location /tutorial
          {
             rewrite ^(/tutorial/.*)/wordpress/(\w+)\.?.*$ $1/cms/$2.php last;
          }
          ...
          ...
  }

Erklärung:

• Die erste Backreference ^(/tutorial/.*) erfasst eine eingehende URL, die mit /tutorial/ beginnt.
• Die zweite Backreference (\w+) erfasst ausschließlich den Dateinamen ohne Erweiterung.
• Die beiden erfassten Werte werden über $1 und $2 in die neue URL eingefügt.
• Das Flag last beendet die Verarbeitung der aktuellen Rewrite-Direktiven und veranlasst NGINX anschließend zu einer erneuten Location-Suche.

NGINX Rewrite-Flags

Das Flag einer rewrite-Direktive bestimmt, wie NGINX nach einer URL-Umschreibung weiterverfährt. Insgesamt stehen vier unterschiedliche Flags zur Verfügung, die jeweils ein eigenes Verhalten definieren. Die folgenden Beispiele zeigen die Funktionsweise und geeignete Einsatzbereiche.

Das Break-Flag

Das Flag break weist NGINX an, die weitere Verarbeitung von Rewrite-Regeln sofort zu beenden und die umgeschriebene URI innerhalb des aktuellen Location-Blocks weiterzuverarbeiten.

Ein Beispiel:

location /test {
    rewrite ^/test$ /new break;
}

Geht eine Anfrage für /test ein, ändert NGINX die URI intern zu /new und wertet keine weiteren Rewrite-Direktiven mehr aus. Die neue URI wird nicht erneut gegen andere Location-Blöcke geprüft. Stattdessen verarbeitet der aktuelle Location-Block die Anfrage weiter.

Dieses Verhalten eignet sich besonders dann, wenn eine URL intern geändert werden soll, die restliche Verarbeitung jedoch im selben Location-Block bleiben muss. Für den Client bleibt die Umschreibung unsichtbar, sodass in der Adresszeile des Browsers weiterhin die ursprüngliche URL angezeigt wird.

Das Last-Flag

Das Flag last unterscheidet sich von break, da NGINX nach der Umschreibung der URI eine neue Suche nach einem passenden Location-Block startet.

Das folgende Beispiel veranschaulicht dieses Verhalten:

location /test {
    rewrite ^/test$ /new last;
}

location /new {
    return 200 "Handled by /new location";
}

Bei einer Anfrage nach /test schreibt NGINX die URI zu /new um und beendet anschließend die Rewrite-Verarbeitung im aktuellen Location-Block. Anders als bei break bleibt NGINX jedoch nicht im bisherigen Block, sondern sucht erneut nach einem Location-Block, der zu /new passt.

In dieser Konfiguration wird die Anfrage vom Location-Block /new verarbeitet. Dieser gibt den HTTP-Status 200 zusammen mit der Meldung „Handled by /new location“ zurück. Das Flag last ist somit dann geeignet, wenn die umgeschriebene URI anschließend von einem anderen Location-Block verarbeitet werden soll.

Wichtig: Eine falsche Verwendung von last kann zu einer Endlosschleife führen, wenn der neu ausgewählte Location-Block erneut eine Rewrite-Regel mit last ausführt, die wiederum auf dasselbe Muster passt.

Das Redirect-Flag

Mit dem Flag redirect weist NGINX den Client mithilfe eines HTTP-302-Statuscodes darauf hin, dass die angeforderte Ressource vorübergehend unter einer anderen URL erreichbar ist.

Beispiel:

location /old {
    rewrite ^/old$ /new redirect;
}

Fordert ein Client /old an, antwortet NGINX mit einem HTTP 302 Temporary Redirect und liefert /new als neues Ziel. Der Browser sendet daraufhin eine neue Anfrage an /new und aktualisiert die angezeigte URL in der Adresszeile.

Während break und last interne Umschreibungen durchführen, erzeugt redirect eine clientseitige Weiterleitung. Der Browser wird also ausdrücklich über die geänderte URL informiert. Dieses Flag eignet sich für vorübergehende URL-Änderungen, Tests oder kurzfristige Migrationen, die später wieder rückgängig gemacht werden können.

Das Permanent-Flag

Das Flag permanent funktioniert ähnlich wie redirect, verwendet jedoch anstelle von HTTP 302 den Statuscode HTTP 301 und signalisiert damit eine dauerhafte Weiterleitung.

Ein Beispiel:

location /old {
    rewrite ^/old$ /new permanent;
}

Bei einer Anfrage nach /old sendet NGINX eine HTTP-301-Antwort und teilt dem Client mit, dass sich die Ressource dauerhaft unter /new befindet. Der Browser ruft anschließend die neue Adresse auf und aktualisiert die URL in der Adresszeile.

Dauerhafte Weiterleitungen können von Browsern und Suchmaschinen zwischengespeichert werden. Dadurch ist es möglich, dass spätere Anfragen nach /old direkt zu /new führen, ohne dass der ursprüngliche Server erneut kontaktiert wird.

Das Flag permanent eignet sich für langfristige URL-Änderungen, insbesondere bei SEO-relevanten Content-Migrationen, da Suchmaschinen Rankingsignale auf die neue URL übertragen können. Wegen der möglichen Zwischenspeicherung von HTTP-301-Weiterleitungen sollte dieses Flag jedoch mit Bedacht eingesetzt werden, da nachträgliche Korrekturen unter Umständen erst verzögert wirksam werden.

Weitere Einsatzmöglichkeiten für NGINX Rewrite-Regeln

Neben einfachen URL-Umschreibungen bietet NGINX weitere praktische Möglichkeiten für typische Server-Konfigurationen. Die folgenden Beispiele zeigen zusätzliche Szenarien, die in realen Umgebungen häufig vorkommen.

SEO-freundliche Weiterleitungen

Angenommen, die Struktur einer Website wird geändert und sämtliche Inhalte unterhalb von /blog/ sollen nach /articles/ verschoben werden, während der restliche Teil jeder URL erhalten bleibt. Eine entsprechende Weiterleitung kann so aussehen:

rewrite ^/blog/(.*)$ /articles/$1 permanent;

Dieses Vorgehen eignet sich für die Umstrukturierung der Inhaltshierarchie einer Website. Der Ausdruck (.*) erfasst innerhalb des URI-Pfads alles, was hinter /blog/ steht. Query-Strings bleiben automatisch erhalten, solange sie nicht ausdrücklich verändert werden. Beispiele:

• /blog/2024/01/post-name → /articles/2024/01/post-name
• /blog/category/tech → /articles/category/tech

Das Flag permanent erzeugt eine HTTP-301-Antwort und ist deshalb bei SEO-orientierten Migrationen von Bedeutung. Es signalisiert Suchmaschinen, dass ein Inhalt dauerhaft verschoben wurde. Rankingsignale und Linkautorität können dadurch mit den neuen URLs verknüpft werden. Gleichzeitig lässt sich vermeiden, dass dieselben Inhalte unter mehreren URLs erscheinen, während die Sichtbarkeit in Suchmaschinen bei der Umstrukturierung möglichst erhalten bleibt.

Reverse-Proxy-Umschreibungen

Wird NGINX als Reverse Proxy verwendet, können Backend-Server Weiterleitungen mit internen URLs zurückgeben, auf die externe Clients keinen Zugriff haben. Solche internen Adressen können in öffentlich erreichbare URLs umgeschrieben werden, bevor NGINX die Antwort an den Client sendet. Eine grundlegende Konfiguration sieht folgendermaßen aus:

proxy_redirect http://backend:8080/ /;

Die Direktive proxy_redirect gehört zum NGINX-Proxy-Modul und verändert die Header Location und Refresh, die von weitergeleiteten Backend-Servern zurückgegeben werden. Die Funktionsweise lässt sich wie folgt beschreiben:

• Sendet ein Backend unter http://backend:8080 beispielsweise den Redirect-Header Location: http://backend:8080/dashboard, ändert NGINX diesen vor der Weitergabe an den Client zu Location: /dashboard.
• Dadurch wird verhindert, dass externe Benutzer interne Backend-Adressen sehen oder versuchen, diese direkt aufzurufen, obwohl sie möglicherweise nicht öffentlich erreichbar sind.
• Ohne diese Anpassung könnten Benutzer fehlerhafte oder nicht erreichbare Weiterleitungen erhalten, wenn eine Backend-Anwendung auf ihre interne Adresse verweist.
• Das allgemeine Format lautet proxy_redirect original_url replacement_url.

Für dynamischere Konfigurationen können ebenfalls Variablen verwendet werden:

proxy_redirect http://backend:8080/ $scheme://$host/;

Die Map-Direktive für komplexe Bedingungen verwenden

Eine große Anzahl einzelner Rewrite-Regeln kann bei vielen URL-Weiterleitungen schnell unübersichtlich und ineffizient werden. Die Direktive map bietet eine alternative Möglichkeit, umfangreichere bedingte URL-Zuordnungen zentral zu verwalten. Ein einfaches Beispiel:

map $request_uri $new_uri {
    /old-page /new-page;
}

Die Direktive map erzeugt auf Basis eines Mustervergleichs eine Variable und kann bei vielen URL-Zuordnungen effizienter sein als zahlreiche einzelne if-Anweisungen oder Rewrite-Regeln. Ein umfangreicheres Beispiel:

map $request_uri $new_uri {
    default "";
    /old-page /new-page;
    /blog/old-post /articles/new-post;
    /products/legacy-item /shop/current-item;
    ~^/category/(.*)$ /browse/$1;
}

server {
    if ($new_uri != "") {
        return 301 $new_uri;
    }
}

Vorteile der Verwendung von map:

• Performance: Map-Definitionen werden beim Laden der Konfiguration vorbereitet und in Hash-Tabellen gespeichert. Dadurch sind Abfragen sehr schnell und müssen nicht wie zahlreiche Rewrite-Regeln nacheinander verarbeitet werden.
• Wartbarkeit: URL-Zuordnungen lassen sich zentral an einer Stelle verwalten, anstatt sie über viele verschiedene Location-Blöcke zu verteilen.
• Flexibilität: Die Direktive unterstützt exakte Übereinstimmungen, reguläre Ausdrücke mit dem Präfix ~ sowie Standardwerte.
• Bedingte Logik: Die erzeugte Variable kann im Server- oder Location-Kontext geprüft werden, sodass eine Weiterleitung nur unter den passenden Bedingungen erfolgt.

Der Eintrag default "" weist $new_uri einen leeren Wert zu, wenn keine Zuordnung gefunden wird. Über eine if-Bedingung lässt sich dieser Wert anschließend überprüfen, sodass nur für tatsächlich zugeordnete URIs eine Weiterleitung ausgeführt wird.

Häufig gestellte Fragen zu NGINX Rewrite-Regeln

1. Was ist der Unterschied zwischen den Direktiven Return und Rewrite in NGINX?

Die Direktive return beendet die Verarbeitung unmittelbar und sendet eine Antwort beziehungsweise Weiterleitung an den Client. Die Direktive rewrite verändert dagegen die Request-URI und kann die interne Verarbeitung anschließend fortsetzen. Dadurch kann die geänderte URI erneut anhand von Location-Blöcken ausgewertet werden. Für einfache Weiterleitungen ist return üblicherweise schneller und eindeutiger. rewrite sollte eingesetzt werden, wenn URI-Transformationen auf Basis regulärer Ausdrücke erforderlich sind.

2. Welche Funktion haben die Flags Last und Break in einer NGINX Rewrite-Regel?

Das Flag last beendet die aktuelle Rewrite-Verarbeitung und startet mit der umgeschriebenen URI eine neue Suche nach einem passenden Location-Block. Das Flag break beendet ebenfalls die Verarbeitung weiterer Rewrite-Direktiven, bleibt jedoch im aktuellen Location-Block und führt keine erneute Zuordnung durch. Vereinfacht ausgedrückt löst last eine interne Weiterleitung mit neuer Location-Suche aus, während break die Rewrite-Verarbeitung an der aktuellen Stelle beendet. last eignet sich, wenn eine andere Location die neue URI verarbeiten soll. break ist sinnvoll, wenn die URI geändert, die Anfrage aber weiterhin im aktuellen Location-Block behandelt werden soll.

3. Wie leite ich HTTP in NGINX auf HTTPS um?

Platziere eine return 301-Direktive in einem Server-Block, der auf Port 80 lauscht:

server {
    listen 80;
    server_name example.com www.example.com;
    return 301 https://$host$request_uri;
}

Die Variable $host übernimmt den angeforderten Domainnamen, während $request_uri den Pfad einschließlich vorhandener Query-Parameter beibehält. Der Client erhält eine permanente HTTP-301-Weiterleitung und wechselt dadurch zu HTTPS. Eine rewrite-Regel ist für diesen Zweck nicht erforderlich, da return effizienter arbeitet und die gewünschte Konfiguration eindeutiger beschreibt. Während return die Verarbeitung unmittelbar beendet, könnte eine Rewrite-Regel unnötigerweise weitere Konfigurationsschritte durchlaufen.

4. Wie kann ich NGINX Rewrite-Regeln testen, ohne den Server neu zu starten?

Mit nginx -t lässt sich die Syntax der Konfiguration prüfen, bevor Änderungen übernommen werden. Das Verhalten von Weiterleitungen kann mit curl -I anhand der Response-Header getestet werden. Mit curl -L können vollständige Weiterleitungsketten verfolgt werden. Für eine detailliertere Fehlersuche lässt sich das Rewrite-Logging aktivieren, indem rewrite_log on; im HTTP- oder Server-Kontext eingetragen wird. Anschließend kann das NGINX-Error-Log auf der Stufe notice ausgewertet werden. Dort ist sichtbar, welche Rewrite-Regeln greifen und wie URIs verändert werden, sodass sich Probleme analysieren lassen, ohne laufenden Traffic zu beeinträchtigen.

5. Kann ich Regex Capture Groups in NGINX Rewrite-Regeln verwenden?

Ja. NGINX unterstützt Capture Groups aus regulären Ausdrücken innerhalb von Rewrite-Regeln. Klammern ( ) definieren eine Gruppe, in der der passende Teil der Request-URI gespeichert wird. Die erfassten Werte stehen anschließend als nummerierte Variablen wie $1, $2, $3 und weitere zur Verfügung und können in der Ersetzung verwendet werden. Ein Beispiel:

rewrite ^/user/(\w+)$ /profile.php?username=$1 last;

In dieser Regel erfasst (\w+) ein oder mehrere Wortzeichen hinter /user/. Fordert ein Client beispielsweise /user/johndoe an, speichert NGINX johndoe in $1 und schreibt die URI zu /profile.php?username=johndoe um. Innerhalb eines einzigen Musters können mehrere Capture Groups verwendet und anschließend einzeln in der Ersatzzeichenfolge angesprochen werden. Dadurch lassen sich auch komplexere URL-Strukturen flexibel transformieren.

6. Wann sollte ich die Map-Direktive anstelle von Rewrite-Regeln verwenden?

map eignet sich besonders dann, wenn viele URL-Zuordnungen verwaltet werden müssen, die andernfalls eine lange Folge von rewrite– oder if-Anweisungen erfordern würden. NGINX verarbeitet Map-Definitionen beim Laden der Konfiguration und speichert die Zuordnungen in Hash-Tabellen, wodurch schnelle Abfragen möglich sind. Das ist beispielsweise bei größeren URL-Migrationen mit Dutzenden oder Hunderten von Weiterleitungen hilfreich. Durch die zentrale Verwaltung in einem map-Block bleibt die Konfiguration außerdem übersichtlicher und leichter wartbar als bei vielen über verschiedene Location-Blöcke verteilten Rewrite-Regeln.

7. Was ist Proxy_redirect und wann wird es benötigt?

Die Direktive proxy_redirect verändert die Header Location und Refresh, die von Upstream-Servern zurückgegeben werden, bevor die Antwort an den Client weitergeleitet wird. Sie ist sinnvoll, wenn eine Backend-Anwendung absolute URLs mit internen Adressen erzeugt, auf die externe Clients nicht zugreifen können. Sendet das Backend beispielsweise Location: http://backend:8080/dashboard, kann proxy_redirect http://backend:8080/ /; daraus /dashboard machen. Auch Variablen lassen sich verwenden, beispielsweise mit proxy_redirect http://backend:8080/ $scheme://$host/;, um das ursprünglich vom Client verwendete Protokoll und den Hostnamen beizubehalten.

8. Warum verursacht eine NGINX Rewrite-Regel eine Endlosschleife?

Eine Endlosschleife kann entstehen, wenn eine umgeschriebene URI erneut auf denselben Location-Block passt und dadurch dieselbe Rewrite-Regel noch einmal ausgelöst wird. Wird beispielsweise /user innerhalb eines Location-Blocks für /user zu /user/profile umgeschrieben, kann eine Schleife entstehen, weil auch /user/profile weiterhin auf diesen Location-Block passt. Eine Möglichkeit besteht darin, break anstelle von last zu verwenden, damit nach dem Umschreiben keine neue Location-Suche stattfindet. Alternativ kann das Location-Muster so präzise definiert werden, dass die umgeschriebene URI nicht mehr darauf passt. Ein Beispiel dafür ist location ~ ^/user/[0-9]+$, wodurch nur ein genau festgelegtes URL-Muster erfasst wird. Mit curl -L lassen sich zudem komplette Redirect-Ketten verfolgen, um die Ursache einer Schleife zu finden.

Zusammenfassung

In diesem Tutorial wurden die beiden wichtigsten NGINX-Direktiven für URL-Umschreibungen behandelt. Die Direktive return eignet sich besonders für einfache Weiterleitungen, da sie die Verarbeitung unmittelbar beendet und effizient arbeitet. Die Direktive rewrite bietet dagegen mehr Möglichkeiten, wenn URLs mithilfe regulärer Ausdrücke transformiert werden müssen.

Außerdem wurden die vier verfügbaren Rewrite-Flags erläutert. break beendet die Rewrite-Verarbeitung innerhalb des aktuellen Location-Blocks, während last eine neue Location-Suche startet. Die Flags redirect und permanent erzeugen clientseitige Weiterleitungen mit HTTP 302 beziehungsweise HTTP 301.

Für komplexere Konfigurationen kann proxy_redirect verwendet werden, um Redirect-Header von Upstream-Servern anzupassen. Die Direktive map ermöglicht eine effiziente Verwaltung größerer Mengen von URL-Zuordnungen. Wer die NGINX-Verarbeitungsreihenfolge kennt – zuerst der Server-Kontext, anschließend die Location-Auswahl und danach die dort definierten Rewrite-Regeln –, kann typische Konfigurationsprobleme wie Endlosschleifen bei Weiterleitungen besser vermeiden.