Umstieg von Apache und .htaccess auf Nginx

• Server und Infrastruktur
• Aktualisiert: 04.10.2026
• Ca. 10 Min. Lesezeit

Logik und Reihenfolge des Umstiegs

1. 1

   Den grundlegenden Unterschied verstehen

   • Ort der Regeln: Bei Apache können die Regeln in .htaccess-Dateien über mehrere Ordner verteilt sein. Bei Nginx stehen alle in der Serverkonfiguration: in der Regel eine Datei je Website mit einem server { … }-Block. Wo die Dateien liegen, hängt von der Distribution ab (/etc/nginx/conf.d ist verbreitet; /etc/nginx/sites-available ist die Struktur von Debian/Ubuntu).
   • Inkrafttreten: Eine .htaccess gilt, sobald sie gespeichert ist. Bei Nginx wird eine Änderung mit nginx -t getestet und mit dem Neuladen (Reload) wirksam. Eine fehlerhafte Konfiguration fällt beim Test auf; die laufende Website bleibt unberührt.
   • Berechtigung: Die Konfiguration zu ändern, erfordert Administratorrechte auf dem Server. Beim Shared Hosting besteht dieser Zugriff meist nicht; dort setzen der Hosting-Anbieter oder das Verwaltungspanel die Regeln um.
   • Herangehensweise: Bei Apache wird alles mit RewriteRule gelöst. Bei Nginx wird die Anfrage zunächst einer location zugeordnet; anschließend gelten die Direktiven dieser Location.

   : Vergrößern

2. 2

   Den Umstieg planen

   1. Bestand aufnehmen: Suchen Sie alle .htaccess-Dateien der Website; die in Unterordnern (Verwaltungsbereich, Upload-Ordner) werden leicht vergessen. Sehen Sie sich auch die Regeln in der Datei des virtuellen Hosts (VirtualHost) von Apache an.
   2. Regeln einordnen: Weiterleitungen, URL-Umschreibung, Zugriffsbeschränkungen, Header, PHP-Einstellungen. Übernehmen Sie nicht, was nicht mehr gebraucht wird.
   3. Nginx-Entsprechungen schreiben (siehe die folgenden Abschnitte).
   4. Testen: nginx -t, danach die Testliste in der Testumgebung.
   5. Umstellen und beobachten: Verfolgen Sie das Fehlerprotokoll in den ersten Tagen genau.

   Bash

   # Alle .htaccess-Dateien der Website auflisten (Pfad durch Ihr eigenes Website-Verzeichnis ersetzen)
   find /var/www/beispiel.de -name ".htaccess" -type f
   
   # Nginx-Konfiguration testen; wenn alles in Ordnung ist, neu laden
   sudo nginx -t && sudo systemctl reload nginx

   : Vergrößern

3. 3

   Die Rangfolge beim location-Abgleich kennen

   .htaccess-Regeln laufen der Reihe nach von oben nach unten ab. Bei Nginx dagegen bearbeitet genau eine location die Anfrage, und welche gewählt wird, hängt nicht von der Schreibreihenfolge ab, sondern von dieser Rangfolge:

   1. location = /adresse: Bei exakter Übereinstimmung wird sie sofort gewählt.
   2. Unter den Präfix-Locations wird die längste Übereinstimmung ermittelt. Ist diese Location mit ^~ geschrieben, wird sie gewählt, und reguläre Ausdrücke werden nicht mehr geprüft.
   3. Locations mit regulärem Ausdruck (~ mit, ~* ohne Beachtung der Groß- und Kleinschreibung) werden in der Reihenfolge der Datei geprüft; die erste passende wird gewählt.
   4. Passt kein regulärer Ausdruck, gilt die in Schritt 2 gefundene längste Präfix-Location.

   Die Folge: Ein Passwortschutz in location /verwaltung/ wird auf die Anfrage /verwaltung/index.php nicht angewendet, denn diese Anfrage wird von location ~ \.php$ bearbeitet. Die Lösung besteht darin, die Location mit ^~ zu schreiben und die PHP-Location darin zu verschachteln (siehe das Beispiel im Abschnitt zur Zugriffsbeschränkung).

   : Vergrößern

4. 4

   PHP an PHP-FPM anbinden

   In den meisten Installationen führt Apache PHP in sich selbst aus (mod_php). Nginx enthält kein PHP; es reicht .php-Anfragen mit fastcgi_pass an den getrennt laufenden Dienst PHP-FPM weiter.

   Nginx

   location ~ \.php$ {
       # Nicht an PHP-FPM senden, wenn die Datei nicht existiert
       try_files $uri =404;
   
       include fastcgi_params;
       fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
   
       # Der Socket-Pfad hängt von Distribution und PHP-Version ab
       fastcgi_pass unix:/run/php/php-fpm.sock;
   }

   Die Zeile try_files $uri =404; verhindert, dass eine nicht vorhandene .php-Adresse an PHP-FPM geschickt wird. Zu Socket-Pfad und Pool-Einstellungen siehe die Anleitung Nginx und PHP-FPM.

   : Vergrößern

Entsprechungstabelle

Front Controller

Die meisten PHP-Frameworks und Content-Management-Systeme leiten jede nicht vorhandene Adresse an die Datei index.php. Bei Apache geschieht das mit einer RewriteRule unter den Bedingungen „keine Datei, kein Ordner“:

RewriteEngine On
# Ist das Angeforderte keine echte Datei und kein echter Ordner, an index.php übergeben
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^ index.php [L]

Bei Nginx ist dieselbe Aufgabe eine einzige Zeile. try_files prüft nacheinander Datei und Ordner; gibt es beides nicht, wird die Anfrage an den letzten Wert übergeben:

root /var/www/beispiel.de/public;
index index.php index.html;

# Form 1: Die Anwendung liest den Pfad aus REQUEST_URI (die meisten Frameworks)
location / {
    try_files $uri $uri/ /index.php?$query_string;
}

# Form 2: Die Anwendung liest den Pfad aus einem Parameter (index.php?url=...)
# Verwenden Sie statt der obigen "location /" diese beiden:
#
# location / {
#     try_files $uri $uri/ @app;
# }
# location @app {
#     rewrite ^/(.*)$ /index.php?url=$1 last;
# }

Liest Ihre Anwendung den Pfad aus einem Abfrageparameter (z. B. index.php?url=…), verwenden Sie die zweite Form im Beispiel. rewrite hängt die ursprüngliche Abfragezeichenfolge von selbst an die neue Adresse an (das Gegenstück zu QSA bei Apache).

Weiterleitung auf HTTPS und www

RewriteEngine On
RewriteCond %{HTTPS} off [OR]
RewriteCond %{HTTP_HOST} !^www\. [NC]
RewriteRule ^ https://www.beispiel.de%{REQUEST_URI} [L,R=301]

Bei Nginx schreibt man dafür keine Bedingung. Für jeden Namen, der weitergeleitet werden soll, wird ein eigener server-Block angelegt, der nur return 301 enthält; die eigentliche Website bleibt in ihrem eigenen Block:

# 1) Alles, was über HTTP eintrifft -> HTTPS + www
server {
    listen 80;
    server_name beispiel.de www.beispiel.de;
    return 301 https://www.beispiel.de$request_uri;
}

# 2) HTTPS, aber ohne www -> www
server {
    listen 443 ssl;
    server_name beispiel.de;
    ssl_certificate     /etc/letsencrypt/live/beispiel.de/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/beispiel.de/privkey.pem;
    return 301 https://www.beispiel.de$request_uri;
}

# 3) Die eigentliche Website
server {
    listen 443 ssl;
    server_name www.beispiel.de;
    ssl_certificate     /etc/letsencrypt/live/beispiel.de/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/beispiel.de/privkey.pem;

    root /var/www/beispiel.de/public;
    index index.php index.html;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
}

Damit eine über HTTPS eintreffende Anfrage an beispiel.de weitergeleitet werden kann, braucht auch dieser Block ein gültiges Zertifikat. Zur Einrichtung des Zertifikats siehe die Anleitung HTTPS in Nginx.

Einzelne Adressen weiterleiten und saubere URLs

# Weiterleitung einer einzelnen Adresse
Redirect 301 /alte-seite.html https://www.beispiel.de/neue-seite

# Einen ganzen Bereich verschieben
RedirectMatch 301 ^/blog/(.*)$ https://www.beispiel.de/artikel/$1

# Saubere URL: /produkt/42 -> produkt.php?id=42
RewriteEngine On
RewriteRule ^produkt/([0-9]+)/?$ produkt.php?id=$1 [L,QSA]

# Weiterleitung einer einzelnen Adresse
location = /alte-seite.html {
    return 301 https://www.beispiel.de/neue-seite;
}

# Einen ganzen Bereich verschieben (Abfrageparameter bleiben erhalten)
location ~ ^/blog/(.*)$ {
    return 301 https://www.beispiel.de/artikel/$1$is_args$args;
}

# Saubere URL: /produkt/42 -> /produkt.php?id=42
# Das Muster beginnt mit /; die ursprüngliche Abfragezeichenfolge wird von selbst angehängt
rewrite ^/produkt/([0-9]+)/?$ /produkt.php?id=$1 last;

• Muster in der .htaccess haben keinen führenden Schrägstrich (^produkt/…); bei Nginx beginnt die Adresse immer mit / (^/produkt/…). Das ist die Einzelheit, die beim Übersetzen am häufigsten vergessen wird.
• Wenn Sie nur weiterleiten möchten, verwenden Sie return 301 statt rewrite … permanent; das ist schlichter und besser lesbar.
• last startet die Suche nach der location mit der neuen Adresse erneut; so erreicht /produkt.php die PHP-Location.
• Müssen Sie Dutzende alter Adressen weiterleiten, ist eine Zuordnungstabelle mit der Direktive map übersichtlicher als eine eigene location für jede Adresse.

Verzeichnisschutz, IP-Beschränkung und versteckte Dateien

# /verwaltung/.htaccess : Passwortschutz
AuthType Basic
AuthName "Panel"
AuthUserFile /home/beispiel/.htpasswd
Require valid-user

# /berichte/.htaccess : nur bestimmte IP-Adressen (Apache 2.4)
Require ip 203.0.113.10
Require ip 10.0.0.0/24

# .htaccess im Stammverzeichnis: Verzeichnisauflistung abschalten, Adressen mit führendem Punkt sperren
Options -Indexes
RewriteEngine On
RewriteRule (^|/)\.(?!well-known) - [F]

# Dateien und Ordner mit führendem Punkt (.htaccess, .env, .git ...) sind gesperrt;
# .well-known bleibt für die Zertifikatsvalidierung offen. Vor die übrigen Locations mit regulärem Ausdruck schreiben.
location ~ /\.(?!well-known) {
    deny all;
}

# Passwortschutz. ^~ : Locations mit regulärem Ausdruck (z. B. \.php$) werden nicht geprüft;
# deshalb wird die PHP-Location innen erneut definiert, und der Schutz umfasst auch .php-Dateien.
location ^~ /verwaltung/ {
    auth_basic "Panel";
    auth_basic_user_file /etc/nginx/.htpasswd;

    location ~ \.php$ {
        try_files $uri =404;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_pass unix:/run/php/php-fpm.sock;
    }
}

# Nur bestimmte IP-Adressen
location ^~ /berichte/ {
    allow 203.0.113.10;
    allow 10.0.0.0/24;
    deny all;

    location ~ \.php$ {
        try_files $uri =404;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        fastcgi_pass unix:/run/php/php-fpm.sock;
    }
}

# Verzeichnisauflistung: standardmäßig ohnehin aus; die ausdrückliche Angabe ist optional
autoindex off;

• Passwortdatei: Eine mit htpasswd erzeugte Datei lässt sich in den meisten Fällen auch mit Nginx verwenden. Prüfen Sie durch eine tatsächliche Anmeldung, ob das Hash-Verfahren der Passwörter unterstützt wird; legen Sie die Datei außerhalb des Web-Stammverzeichnisses ab.
• IP-Beschränkung: allow und deny werden in der geschriebenen Reihenfolge ausgewertet; die erste passende Regel gilt. Steht vor der Website ein CDN oder ein anderer Proxy, sieht Nginx die IP-Adresse des Proxys und nicht die des Besuchers; solange die echte Adresse nicht eigens konfiguriert ist, wirkt die IP-Beschränkung nicht wie erwartet.
• Verzeichnisauflistung: Bei Nginx ist autoindex standardmäßig ausgeschaltet; eine Entsprechung für die Zeile Options -Indexes ist nicht zwingend nötig.
• Versteckte Dateien: Die Standardkonfiguration von Apache verbirgt Dateien, die mit .ht beginnen, von selbst; bei Nginx gibt es keine solche Voreinstellung. Nach dem Umstieg lässt sich der Inhalt zurückgebliebener .htaccess-, .env- oder .git-Dateien als Klartext herunterladen. Fügen Sie unbedingt die Location hinzu, die Adressen mit führendem Punkt sperrt, und schreiben Sie sie vor die übrigen Locations mit regulärem Ausdruck.
• „Deny from all“ in Unterordnern: Auch der .htaccess-Schutz in Upload- oder Backup-Ordnern greift nicht mehr; schreiben Sie für jeden eine location. Siehe Nginx-Sicherheitseinstellungen.

Fehlerseiten und Cache-Header

# Eigene Fehlerseiten
ErrorDocument 404 /404.html
ErrorDocument 500 /500.html

# Cache-Header (mod_expires)
<IfModule mod_expires.c>
    ExpiresActive On
    ExpiresByType text/css "access plus 30 days"
    ExpiresByType application/javascript "access plus 30 days"
    ExpiresByType image/webp "access plus 90 days"
    ExpiresByType image/jpeg "access plus 90 days"
</IfModule>

# Eigene Fehlerseiten
error_page 404 /404.html;
error_page 500 502 503 504 /50x.html;

# Cache-Header
location ~* \.(?:css|js)$ {
    expires 30d;
}
location ~* \.(?:webp|jpg|jpeg|png|gif|svg|ico)$ {
    expires 90d;
}

Bei Fehlerantworten, die PHP erzeugt (etwa ein 404 aus der Anwendung), greift error_page nicht von selbst; dafür ist in der betreffenden Location fastcgi_intercept_errors on; erforderlich. Zu Cache-Dauer und Komprimierung siehe die Anleitung Caching und Komprimierung.

Zeilen mit php_value und php_flag

Zeilen mit php_value und php_flag in der .htaccess funktionieren nur mit mod_php. Nginx liest sie nicht, PHP-FPM ebenso wenig. Es gibt zwei Entsprechungen:

• PHP-FPM-Pool-Einstellung: php_value[…] / php_flag[…] oder php_admin_value[…] / php_admin_flag[…], die die Anwendung nicht überschreiben kann. Nach der Änderung wird PHP-FPM neu geladen.
• .user.ini: Liegt im Ordner der Website und erfordert kein Neuladen; sie gilt jedoch nur für Einstellungen, die auf Verzeichnisebene geändert werden dürfen, und da PHP die Datei in Abständen neu einliest (standardmäßig 300 Sekunden), ist eine Änderung möglicherweise nicht sofort sichtbar.

# Funktioniert nur mit mod_php; Nginx + PHP-FPM liest diese Zeilen nicht
php_value upload_max_filesize 32M
php_value post_max_size 32M
php_value memory_limit 256M
php_flag display_errors off

; Möglichkeit 1: eine Datei .user.ini im Stammverzeichnis der Website
upload_max_filesize = 32M
post_max_size = 32M
memory_limit = 256M
display_errors = Off

; Möglichkeit 2: die PHP-FPM-Pool-Datei (z. B. www.conf; der Ort hängt von der Distribution ab)
; Einen mit php_admin_* gesetzten Wert kann die Anwendung nicht per ini_set() ändern
php_admin_value[upload_max_filesize] = 32M
php_admin_value[post_max_size] = 32M
php_admin_value[memory_limit] = 256M
php_admin_flag[display_errors] = off

Wenn Sie ein Upload-Limit übernehmen, denken Sie auch an die Nginx-Seite: Der Standardwert von client_max_body_size ist 1m; wird er nicht erhöht, werden große Uploads mit dem Fehler 413 abgewiesen, bevor sie PHP überhaupt erreichen.

Die Direktive „if“ und weitere Stolperfallen

• if ist keine Bedingung wie in einer Programmiersprache. Innerhalb einer location lassen sich mit if nur return und rewrite gefahrlos verwenden; zusammen mit anderen Direktiven kann es zu unerwarteten Ergebnissen kommen. Statt RewriteCond-Zeilen eins zu eins in if zu übersetzen, fragen Sie zuerst: Lässt sich das mit try_files, return, einem eigenen server- oder location-Block oder mit map lösen? Meistens ja.
• Unterschied in der Reihenfolge: .htaccess-Regeln werden nacheinander abgearbeitet und beeinflussen einander; bei Nginx wird eine einzige Location gewählt. Die Regeln in derselben Reihenfolge untereinanderzuschreiben, führt nicht zum selben Ergebnis.
• Vererbung: Direktiven wie add_header werden nicht von der übergeordneten Ebene geerbt, sobald dieselbe Direktive auf der unteren Ebene steht.
• Fertige Umwandlungswerkzeuge: Online-Konverter können einen brauchbaren ersten Entwurf liefern, ihre Ausgabe enthält aber häufig unnötige if-Blöcke. Gehen Sie jede Zeile durch und stellen Sie sicher, dass Sie sie verstehen.
• Die eigene .htaccess der Anwendung: Fertige Software (Content-Management-Systeme, Frameworks) erzeugt bei der Installation eine .htaccess und kann sie bei Updates ändern. Entnehmen Sie die Nginx-Entsprechung dieser Regeln der Dokumentation der Software und prüfen Sie sie nach Updates erneut.

Testliste nach dem Umstieg

# Weiterleitungen: Statuscode und Location-Header
curl -sI http://beispiel.de/ | grep -i -E "^HTTP|^location"
curl -sI https://beispiel.de/ | grep -i -E "^HTTP|^location"
curl -sI https://www.beispiel.de/alte-seite.html | grep -i -E "^HTTP|^location"

# Versteckte Dateien: 403 oder 404 erwartet, kein Inhalt
curl -s -o /dev/null -w "%{http_code}\n" https://www.beispiel.de/.htaccess
curl -s -o /dev/null -w "%{http_code}\n" https://www.beispiel.de/.env
curl -s -o /dev/null -w "%{http_code}\n" https://www.beispiel.de/.git/config

# Passwortgeschützter Bereich: 401 erwartet (auch bei .php)
curl -s -o /dev/null -w "%{http_code}\n" https://www.beispiel.de/verwaltung/index.php

# Nicht vorhandene Adresse: 404
curl -s -o /dev/null -w "%{http_code}\n" https://www.beispiel.de/gibt-es-nicht

• Startseite, eine Unterseite und eine Seite mit sauberer URL (z. B. Produkt, Artikel) lassen sich aufrufen.
• http:// und die Adresse ohne www führen in einem Schritt per 301 zur richtigen HTTPS-Adresse.
• Weiterleitungen alter Adressen funktionieren; Abfrageparameter bleiben erhalten.
• Eine nicht vorhandene Adresse liefert 404 und die eigene Fehlerseite; eine nicht vorhandene .php-Adresse ebenso.
• Der Verwaltungsbereich fragt nach dem Passwort, auch bei .php-Dateien.
• Adressen wie /.htaccess, /.env und /.git/config sind nicht erreichbar.
• Im Upload-Ordner wird kein PHP ausgeführt; es erscheint keine Verzeichnisauflistung.
• Formularversand, Anmeldung und Datei-Upload (auch mit großer Datei) funktionieren.
• Statische Dateien kommen mit korrektem Cache-Control und Content-Type an.
• Die Sicherheitsheader sind vorhanden (siehe Sicherheitsheader).
• In den Fehlerprotokollen von Nginx und PHP-FPM stehen keine unerwarteten Einträge.

Häufige Fragen

Verwandte Anleitungen

• Nginx und PHP-FPM: So laufen PHP-Websites mit Nginxfastcgi_pass, SCRIPT_FILENAME, try_files, das Pool-Konzept, Socket-Berechtigungen und der Fehler 502.
• Nginx-Sicherheitseinstellungen: Ratenbegrenzung, Header, ZugriffsbeschränkungenRatenbegrenzung, Sicherheitsheader, Schutz versteckter Dateien und des Admin-Pfads sowie Anfragegrenzen in Nginx.
• HTTPS in Nginx: SSL-Zertifikat einrichtenZertifikat beziehen, auf HTTPS weiterleiten, HSTS, SSL-Terminierung und automatische Erneuerung in Nginx.
• 502, 504 und andere Nginx-Fehler: Ursachen und LösungenBedeutung, mögliche Ursachen, Diagnose über die Logs und Lösung für 502, 504, 413, 499, 403 und 404.