NGINX Rewrite & Redirect

6 Kernkonzepte

Die wichtigsten NGINX-Direktiven für Rewrite, Redirect und URL-Manipulation: return · rewrite · try_files · Regex · if · Variablen Diese Direktiven ermöglichen die Umleitung von URLs, das Umschreiben von Pfaden, die Implementierung von Clean URLs und die Fehlerbehandlung – essenziell für SEO, Migrationen und moderne Webanwendungen.

return – Einfache Weiterleitungen

return [code] [URL]

location /alt { return 301 /neu; } server { return 301 https://newdomain.com$request_uri; }

return ist die einfachste und effizienteste Methode für Weiterleitungen. Sie können den HTTP-Statuscode und das Ziel angeben – ohne dass weitere Verarbeitung stattfindet.

Häufige Statuscodes

Code	Bedeutung
301	Permanent (dauerhafte Weiterleitung – SEO empfohlen)
302	Temporär (vorübergehende Weiterleitung)
303	See Other (z.B. nach POST)
307	Temporäre Weiterleitung (Methode bleibt erhalten)
308	Permanente Weiterleitung (Methode bleibt erhalten)

Beispiele

# Einzelne URL weiterleiten

location /old-page {

return 301 /new-page;

}

# Domäne weiterleiten (HTTP → HTTPS)

server {

listen 80;

server_name example.com;

return 301 https://$server_name$request_uri;

}

# Domain-Umzug

server {

listen 80 443 ssl;

server_name old-domain.com www.old-domain.com;

return 301 https://new-domain.com$request_uri;

}

# www → non-www (oder umgekehrt)

server {

listen 80;

server_name www.example.com;

return 301 https://example.com$request_uri;

}

Tipp: return ist schneller als rewrite, da die Verarbeitung sofort beendet wird. Verwenden Sie return für einfache Weiterleitungen, rewrite für komplexe URL-Manipulationen.

rewrite – URLs umschreiben

rewrite regex replacement [flag]

rewrite ^/blog/([0-9]+)/(.*)$ /posts/$1/$2 last;

rewrite ändert die URI intern oder führt eine Weiterleitung durch. Mit regulären Ausdrücken können Sie komplexe URL-Strukturen umschreiben.

Flags für rewrite

Flag	Bedeutung
last	Beendet die Verarbeitung im aktuellen location-Block
break	Beendet die Verarbeitung komplett (keine weiteren rewrite-Regeln)
permanent	Externe Weiterleitung mit 301 (permanent)
redirect	Externe Weiterleitung mit 302 (temporär)
last vs break	last sucht nach neuem location, break stoppt sofort

Beispiele

# Interne Umschreibung (SEO-freundliche URLs)

location /blog/ {

rewrite ^/blog/([0-9]+)/(.*)$ /posts/$1/$2 last;

}

# Externe Weiterleitung mit permanent (301)

location /old-folder/ {

rewrite ^/old-folder/(.*)$ /new-folder/$1 permanent;

}

# Query-Parameter auswerten

location /search {

rewrite ^/search\?q=(.*)$ /suchergebnisse?query=$1 last;

}

# Alle Anfragen auf index.php umleiten (WordPress)

location / {

try_files $uri $uri/ /index.php?$args;

}

Tipp: Verwenden Sie last für interne Umschreibungen, die zu einem anderen location-Block passen sollen. break stoppt die Verarbeitung sofort – nützlich für Optimierungen.

try_files – Dateien prüfen und fallback

try_files file1 file2 fallback

location / { try_files $uri $uri/ /index.html; }

try_files prüft, ob eine Datei oder ein Verzeichnis existiert, und gibt bei Erfolg diese zurück. Bei Misserfolg wird der Fallback (z.B. index.html oder eine Error-Seite) ausgeliefert.

Beispiele

# SPA (Single Page Application)

location / {

try_files $uri $uri/ /index.html;

}

# Statische Dateien mit Fallback auf 404

location /assets/ {

try_files $uri /assets/default.png =404;

}

# WordPress mit PHP-FPM

location / {

try_files $uri $uri/ /index.php?$args;

}

# Mehrere Fallbacks

location / {

try_files $uri $uri/index.html /fallback.html =404;

}

# API-Fallback auf Proxy

location /api/ {

try_files $uri @api_fallback;

}

location @api_fallback {

proxy_pass http://localhost:3000;

}

Tipp: try_files ist die empfohlene Methode für SPAs, da sie sicherstellt, dass alle Routen auf index.html fallen und das Frontend-Routing übernimmt.

Reguläre Ausdrücke – Muster für rewrite

^, $, (), \d, \w, [a-z], +, *, ?

# ^ = Anfang, $ = Ende, () = Capture-Gruppe ^/user/([0-9]+)$ # /user/123 → $1 = 123 ^/([a-z]+)/([0-9]+)/$ # /products/42/ → $1=products, $2=42

Reguläre Ausdrücke in NGINX werden von der PCRE-Bibliothek verarbeitet. Sie ermöglichen flexible Mustererkennung für rewrite und location.

Wichtige Regex-Elemente

Muster	Bedeutung
^	Anfang der URI
$	Ende der URI
.	Beliebiges Zeichen (außer Newline)
.*	Beliebige Zeichen (0 oder mehr)
.+	Beliebige Zeichen (1 oder mehr)
[0-9]	Ziffer 0-9
[a-z]	Kleinbuchstaben
\d	Ziffer (äquivalent zu [0-9])
\w	Wortzeichen (a-zA-Z0-9_)
()	Capture-Gruppe (in $1, $2, ... verfügbar)
\|	ODER-Verknüpfung

Beispiele

# Zahlen am Ende extrahieren

rewrite ^/post/([0-9]+)$ /article.php?id=$1 last;

# Sluggified URLs (Buchstaben, Zahlen, Bindestriche)

rewrite ^/blog/([a-zA-Z0-9-]+)/$ /blog.php?slug=$1 last;

# Dateierweiterungen entfernen (SEO)

rewrite ^(.*)\.html$ $1 permanent;

# ODER-Verknüpfung für mehrere Sprachen

rewrite ^/(de|en|fr)/(.*)$ /index.php?lang=$1&page=$2 last;

# Pfade mit optionalen Teilen

rewrite ^/shop/(.*?)/?(.*)$ /shop.php?category=$1&product=$2 last;

Tipp: Testen Sie Ihre Regex-Muster mit Tools wie regex101.com, bevor Sie sie in die NGINX-Konfiguration einfügen. Spezielle Zeichen wie ? und + müssen in manchen Kontexten escaped werden.

if – Bedingte Verarbeitung

if (condition) { directive }

if ($request_method = POST) { return 405; }

if ermöglicht bedingte Ausführungen in der NGINX-Konfiguration. Achtung: if sollte sparsam verwendet werden, da es zu unerwartetem Verhalten führen kann (insbesondere in location-Blöcken).

Häufige if-Bedingungen

Bedingung	Beschreibung
$request_method = POST	Prüft die HTTP-Methode
$http_user_agent ~* "bot"	Prüft den User-Agent (case-insensitive)
$args ~ "debug=1"	Prüft Query-Parameter
-f $request_filename	Prüft, ob die Datei existiert
!-f $request_filename	Prüft, ob die Datei nicht existiert
-d $request_filename	Prüft, ob das Verzeichnis existiert

Beispiele

# POST-Anfragen blockieren

if ($request_method = POST) {

return 405;

}

# Bots erkennen und aussperren

if ($http_user_agent ~* "bot|spider|crawler") {

return 403;

}

# Query-Parameter prüfen

if ($args ~* "debug=1") {

set $debug_mode on;

}

# Datei existiert nicht → 404

if (!-f $request_filename) {

return 404;

}

# Mehrere Bedingungen kombinieren

if ($http_user_agent ~* "bot") {

if ($request_uri ~* "^/admin") {

return 403;

}

⚠️ Vorsicht: if in location-Blöcken kann zu unerwartetem Verhalten führen (siehe "if is evil" in der NGINX-Dokumentation). Verwenden Sie wenn möglich try_files, return oder rewrite.

Variablen – Dynamische Werte in NGINX

$uri · $request_uri · $args · $host · $remote_addr

$uri # Aktuelle URI (normalisiert) $request_uri # Ursprüngliche URI (mit Query-String) $args # Query-Parameter $host # Hostname $remote_addr # Client-IP

Variablen in NGINX enthalten dynamische Werte aus der Anfrage – wie URI, Host, IP oder Query-Parameter. Sie werden in return, rewrite und proxy_pass verwendet.

Wichtige NGINX-Variablen

Variable	Beschreibung
$uri	Aktuelle URI (normalisiert, ohne Query-String)
$request_uri	Ursprüngliche URI (mit Query-String)
$args	Query-String (Parameter)
$host	Hostname aus dem Host-Header
$http_host	Host-Header (wie $host)
$remote_addr	Client-IP-Adresse
$remote_port	Client-Port
$scheme	http oder https
$request_method	HTTP-Methode (GET, POST, etc.)
$http_user_agent	User-Agent-Header
$http_referer	Referer-Header
$server_name	Servername aus der Konfiguration
$document_root	Root-Verzeichnis
$request_filename	Vollständiger Pfad zur Datei

Beispiele

# HTTPS-Weiterleitung mit Variablen

return 301 https://$server_name$request_uri;

# Logging mit benutzerdefinierten Variablen

set $client_ip $remote_addr;

# Query-Parameter extrahieren

if ($args ~* "id=([0-9]+)") {

set $post_id $1;

}

# Proxy mit Client-IP (X-Forwarded-For)

proxy_set_header X-Real-IP $remote_addr;

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

proxy_set_header X-Forwarded-Proto $scheme;

# Rewrite mit Variablen

rewrite ^/old/(.*)$ /new/$1?redirect=1 last;

Tipp: Variablen mit $ können in den meisten Direktiven verwendet werden. $request_uri enthält den kompletten Pfad inklusive Query-String, während $uri normalisiert und ohne Query-String ist.

Rewrite & Redirect im Überblick

return Einfache Weiterleitung
301, 302, 308

rewrite URL umschreiben
Regex, Flags

try_files Dateien prüfen
SPA, Fallback

Regex Mustererkennung
^, $, (), \d

if Bedingte Verarbeitung
Vorsicht bei if!

$vars Dynamische Variablen
$uri, $host, $args

Quick Summary

return

Weiterleitung

rewrite

URL umschreiben

try_files

Dateien prüfen

Regex

Mustererkennung

if

Bedingungen

$vars

Variablen

return 301 /neu · rewrite ^/old/(.*)$ /new/$1 permanent · try_files $uri $uri/ /index.html