Nginx Redirects meistern - Fehler vermeiden, sauber konfigurieren

Weiterleitungen in Nginx sind schnell falsch konfiguriert: Ein kleiner Fehler im Statuscode, im Hostnamen oder im Zusammenspiel von return und rewrite reicht aus, damit Browser falsche Ziele merken oder sich Schleifen bilden. Der Begriff nginx redirect steht in der Praxis meistens für genau diese saubere Steuerung von Host-, Pfad- und Protokollwechseln. Ich zeige dir deshalb, wie ich Weiterleitungen in Nginx aufbaue, welche Statuscodes ich wann einsetze und wie du typische Fälle wie HTTPS, Canonical Host und alte Pfade sauber abbildest.

Was ein Redirect in Nginx technisch auslöst

Ich trenne bei Nginx bewusst zwischen einer sichtbaren Weiterleitung und einer internen Umleitung. Bei einer sichtbaren Weiterleitung bekommt der Browser einen Statuscode wie 301 oder 302 plus einen Location-Header und springt auf die neue Adresse. Bei einer internen Umleitung bleibt die URL im Browser gleich, Nginx verarbeitet den Request aber auf dem Server anders weiter.

Genau deshalb ist nicht jede Regel in Nginx automatisch ein Redirect im klassischen Sinn. return beendet die Verarbeitung sofort und schickt die Antwort an den Client. rewrite verändert dagegen zunächst die URI und kann, je nach Flag, eine neue Locationsuche auslösen. Wenn man diesen Unterschied nicht sauber versteht, baut man schnell Regeln, die funktionieren, aber nicht so, wie man sie später betreiben will.

Für mich ist die wichtigste Faustregel einfach: Wenn der Browser eine neue Adresse sehen soll, muss die Regel das ausdrücklich auslösen. Sobald das klar ist, wird die Konfiguration viel lesbarer und das Risiko für Schleifen sinkt deutlich. Damit ist die technische Basis gelegt, und der nächste Schritt ist die Frage, wo ich eine Weiterleitung in der Praxis am besten platziere.

Die sauberste Lösung für Host- und Pfadwechsel

Für feste Weiterleitungen setze ich fast immer auf einen eigenen server-Block oder auf eine sehr kleine, klar abgegrenzte Location. Nginx entscheidet den passenden Server zunächst über listen und Host; genau deshalb ist es sauberer, einen alten Host direkt auf die neue Zielvariante zu schicken, statt die Logik in einem großen Block zu verstecken. Die offizielle Nginx-Dokumentation macht an dieser Stelle denselben Punkt: Für feste Umzüge ist return der direkte und wartbare Weg.

server {
    listen 80;
    server_name alt-domain.tld;
    return 301 https://neu-domain.tld$request_uri;
}

server {
    listen 443 ssl http2;
    server_name neu-domain.tld;
    # eigentliche Anwendung
}

Ich mag an diesem Muster vor allem zwei Dinge: Erstens ist sofort erkennbar, dass der alte Host keine eigene Anwendungslogik mehr hat. Zweitens bleibt der komplette Pfad mit $request_uri erhalten, also auch vorhandene Query-Parameter. Wenn Nginx die Ziel-URL aus einer lokalen URI erzeugt, spielen außerdem server_name_in_redirect und port_in_redirect hinein. Das ist wichtig, wenn der Location-Header später einen unerwarteten Host oder Port zeigt.

Für reine Pfadwechsel nutze ich das gleiche Prinzip, nur ohne Domainwechsel. Die Regel bleibt kurz, eindeutig und leicht testbar. Sobald das Fundament steht, lohnt sich der Blick auf die Redirect-Typen, die im Alltag wirklich zählen.

Typische Weiterleitungen aus dem Alltag

In Projekten sehe ich immer wieder dieselben drei Fälle: HTTP auf HTTPS, www auf die kanonische Domain und alte Pfade auf neue Inhalte. Ich halte diese Fälle gern getrennt, weil sie unterschiedliche Ziele haben und oft auch unterschiedliche Risiken mitbringen. Ein permanenter Redirect ist nicht automatisch besser, nur weil er „stärker“ wirkt.

HTTP auf HTTPS

Das ist der Klassiker. Ich leite den gesamten Traffic auf Port 80 auf HTTPS um und lasse nur noch einen klaren Zielhost zu. Für Nutzer ist das transparent, für Suchmaschinen ist es nachvollziehbar, und für spätere HSTS-Einführung ist es die richtige Grundlage. Ich würde hier meistens mit 301 arbeiten, außer ich teste gerade noch die Umstellung und will den Browser-Caches nicht sofort eine endgültige Variante geben.

server {
    listen 80;
    server_name beispiel.tld www.beispiel.tld;
    return 301 https://beispiel.tld$request_uri;
}

www auf die kanonische Domain

Hier geht es nicht um Technik, sondern um Konsistenz. Eine kanonische Host-Variante reduziert Duplicate Content, vereinfacht Cookies und macht Logs sowie Monitoring lesbarer. Ich entscheide mich früh für eine Variante und ziehe sie dann konsequent durch alle Weiterleitungen und internen Links.

Wichtig ist nur, dass die Ziel-Domain wirklich eindeutig ist. Wenn du mit $host oder anderen Variablen zu großzügig bist, kannst du unbeabsichtigt die falsche Hostvariante wieder einsammeln. Genau an dieser Stelle entstehen viele Redirect-Loops, obwohl die Syntax auf den ersten Blick harmlos aussieht.

Lesen Sie auch: Nginx Regex Location - Häufige Fehler & Best Practices

Alte Pfade auf neue Inhalte

Bei Relaunches oder Strukturänderungen nutze ich Pfad-Weiterleitungen sehr gezielt. Alte URLs mit dauerhaft hohem Traffic bekommen eine explizite Regel, statt blind auf eine neue Startseite umzuleiten. Das ist besser für Nutzer und deutlich sauberer für Analysen, weil das Ziel semantisch zum Ursprung passt.

location = /alter-artikel {
    return 301 /wissen/neuer-artikel;
}

Wenn ich viele ähnliche Pfade umbiegen muss, gehe ich erst dann zu regulären Ausdrücken über. Damit bin ich bei der eigentlichen Werkzeugwahl angekommen, und genau dort trennt sich in Nginx die elegante Lösung von der unnötig komplizierten.

Wann rewrite sinnvoll ist und wann nicht

rewrite ist kein schlechter Befehl, aber er wird oft überbenutzt. Ich greife darauf zurück, wenn ich eine URI nach einem Muster umformen will, also zum Beispiel bei alten Pfadstrukturen, Sprachpräfixen oder bestimmten Verzeichnisregeln. Für eine einfache feste Weiterleitung ist rewrite dagegen meist die falsche Wahl, weil return kürzer, direkter und leichter zu warten ist.

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

Das Beispiel ist genau dann sinnvoll, wenn alte Blog-URLs strukturell in ein neues Wissensverzeichnis überführt werden. Die Flags sind dabei entscheidend: permanent erzeugt eine 301-Weiterleitung, redirect eine 302-Weiterleitung. last stößt eine neue Locationsuche an, break bleibt in der aktuellen Location. Wenn man das im falschen Kontext einsetzt, landet man schnell in einem Kreislauf. Nginx bricht solche internen Umleitungen nach 10 Durchläufen ab und liefert dann einen 500er Fehler.

Mein praktischer Rat ist deshalb klar: Regex nur dann, wenn sie wirklich Mehrwert bringen. Alles andere gehört in eine einfache, gut lesbare Regel. Damit sind die häufigsten Fehler schon fast automatisch entschärft.

Fehler, die ich in Redirect-Konfigurationen am häufigsten sehe

• Zu viel Logik in einem Block: Wenn Hostwechsel, HTTPS und Pfadumformung in derselben Stelle vermischt werden, verliert man schnell den Überblick.
• Falscher Statuscode: 301 für einen kurzen Test ist eine schlechte Idee, weil Browser und Zwischen-Caches die Weiterleitung lange behalten können.
• Query-Parameter vergessen: Wenn ein Ziel die ursprünglichen Parameter braucht, arbeite ich bewusst mit $request_uri oder einer sauberen Variablenlösung.
• Redirect-Loops: Ein Ziel, das wieder von derselben Regel getroffen wird, erzeugt Schleifen. Das passiert gern bei ungenauem Host-Matching oder bei schlecht platzierten Regex-Regeln.
• Automatische Slash-Weiterleitung übersehen: Wenn eine Location mit Slash endet und dahinter ein Proxy oder Upstream hängt, kann Nginx bei einer Anfrage ohne Slash automatisch ein permanentes 301 auf die Slash-Variante senden.
• Methodenwechsel ignoriert: Für Formulare und APIs ist 307 oder 308 oft die bessere Wahl, weil POST nicht zu GET „umfallen“ soll.

Gerade der Slash-Fall wird oft missverstanden: Er ist nicht automatisch falsch, aber er ist eben auch nicht immer explizit sichtbar konfiguriert. Wenn du solche Effekte kennst, liest du die Konfiguration später deutlich sicherer. Im letzten Schritt prüfe ich deshalb nicht nur die Syntax, sondern auch das tatsächliche Verhalten mit echten Requests.

So prüfe ich eine Weiterleitung in wenigen Minuten

Bevor ich eine Regel produktiv lasse, teste ich sie immer mit einem kurzen, reproduzierbaren Ablauf. Erst prüfe ich die Konfiguration, dann die Antwort des Servers und zuletzt das Verhalten im Browser oder mit einem echten Request. Das spart mir später die unangenehme Suche nach Caches, alten Tabs oder falsch interpretierten Statuscodes.

1. Konfiguration testen: Ich beginne mit nginx -t, damit Syntaxfehler sofort auffallen.
2. Status und Ziel prüfen: Mit curl -I sehe ich den Statuscode und den Location-Header direkt.
3. Temporär vor permanent: Wenn ich mir nicht sicher bin, teste ich erst mit 302 oder 307 und schalte später auf 301 oder 308 um.
4. Formulare separat prüfen: Bei POST-Requests kontrolliere ich zusätzlich, ob die Methode erhalten bleibt.

nginx -t
curl -I http://beispiel.tld/alter-pfad
curl -I https://beispiel.tld/alter-pfad

Wenn ich eine API oder ein Formular absichere, teste ich nicht nur den Header, sondern auch die Request-Methode. Ein Redirect kann korrekt aussehen und trotzdem für POST-Nutzer falsch sein. Genau diese Mischung aus Header-Check und realem Request liefert mir das Bild, das ich für eine saubere Freigabe brauche. Danach bleibt nur noch die Frage, was sich in der Praxis wirklich als Standard bewährt.

Was sich in der Praxis wirklich bewährt

Meine Standardstrategie ist schlicht: feste Weiterleitungen per return, Regex nur mit einem guten Grund, und dauerhafte Umzüge erst dann, wenn die temporäre Variante sauber getestet ist. Für Hosts und Protokolle trenne ich die Logik konsequent, weil die Konfiguration dadurch weniger fehleranfällig und später schneller nachvollziehbar wird.

• Ich leite HTTP früh auf HTTPS um und halte den Zielhost konsistent.
• Ich entscheide mich für eine kanonische Domain und ziehe sie überall durch.
• Ich nutze 301 oder 308 nur dann, wenn das Ziel wirklich dauerhaft ist.
• Ich setze 307 oder 302 ein, wenn ich während einer Migration noch Spielraum brauche.
• Ich prüfe jede Regel auf Loops, Parameterverlust und unerwünschte Slash-Effekte.

Wenn du dich an diese Linien hältst, wird aus einer potenziell fehleranfälligen Redirect-Landschaft eine saubere, gut wartbare Nginx-Konfiguration. Genau das ist am Ende der Punkt, an dem Redirects nicht mehr wie Sonderfälle wirken, sondern wie ein kontrollierter Teil deiner Infrastruktur.