Nginx Location Blöcke erklärt: Routing von Web-Traffic

Nginx Location Blöcke entscheiden, was passiert, nachdem eine Anfrage im richtigen server-Block gelandet ist. Sie sind der Grund, warum /static/app.css von der Festplatte bedient werden kann, /api/users an eine Anwendung weitergeleitet werden kann und /.git/config verweigert werden kann, bevor etwas Vertrauliches preisgegeben wird.

Die meisten Fehler mit Location Blöcken sind keine Syntaxfehler. Es sind Prioritätsfehler. Ein Regex fängt eine Anfrage ab, von der Sie erwartet haben, dass ein Präfix-Block sie behandelt. Ein root-Pfad hängt mehr URI an, als Sie dachten. Ein proxy_pass mit einem abschließenden Schrägstrich schreibt die Upstream-URI anders um als dieselbe Direktive ohne einen. Die folgenden Beispiele konzentrieren sich auf diese tatsächlichen Fehlerquellen.

Die Rolle und Anatomie eines Location Blocks

Ein location-Block definiert, wie Nginx auf Anfragen basierend auf der Request-URI (Uniform Resource Identifier) antworten soll. Diese Blöcke sind immer innerhalb eines server-Blocks verschachtelt.

Wenn ein Client eine Anfrage stellt (z. B. GET /images/logo.png), überprüft Nginx die Request-URI gegen alle definierten Location Blöcke innerhalb des lauschenden server-Blocks, um die entsprechende Behandlung zu bestimmen, wie das Ausliefern einer Datei, das Weiterleiten des Clients oder das Proxying der Anfrage an einen Anwendungsserver.

Grundlegende Syntax

Die Syntax erfordert einen Modifikator (oder dessen Fehlen), gefolgt von einem Muster (URI):

location [modifier] [pattern] {
    # Konfigurationsdirektiven (z. B. root, index, proxy_pass)
}

Verständnis der Location-Match-Typen (Die Modifikatoren)

Nginx bietet eine kleine Auswahl an Location-Match-Stilen. Die Wahl beeinflusst sowohl die Routing-Präzision als auch den Arbeitsaufwand, den Nginx leistet, bevor es einen Handler auswählt.

1. Präfix-Match (Kein Modifikator)

Dies ist der Standard-Match-Typ. Nginx sucht nach der längsten Startzeichenfolge, die mit der Request-URI übereinstimmt.

Modifikator	Beispiel	Verhalten	Beste Verwendung
(keiner)	`location /blog/`	Matcht URIs, die mit `/blog/` beginnen (z. B. `/blog/post/1`).	Allgemeiner Zweck, Definition großer Abschnitte einer Website.

Beispiel:

location /docs/ {
    root /var/www/html/public;
    # Wenn die URI /docs/manual.pdf ist, sucht Nginx nach /var/www/html/public/docs/manual.pdf
}

2. Exakter Match (`=`)

Dieser Modifikator erzwingt einen exakten Match zwischen der URI und dem Muster. Bei einem Match stoppt Nginx sofort die Suche nach anderen Locations. Dies ist der schnellste Match-Typ.

Modifikator	Beispiel	Verhalten	Beste Verwendung
`=`	`location = /favicon.ico`	Matcht nur die URI `/favicon.ico` exakt.	Behandlung spezifischer, häufig angefragter Dateien oder Standardseiten.

3. Längstes Präfix, Nicht-Regex (`^~`)

Dies ist ein spezialisierter Präfix-Match. Wenn Nginx den längsten Präfix-Match mit ^~ findet, stoppt es sofort die Überprüfung aller Regex-Location-Blöcke und überschreibt sie damit effektiv.

Modifikator	Beispiel	Verhalten	Beste Verwendung
`^~`	`location ^~ /assets/`	Matcht URIs, die mit `/assets/` beginnen, und verhindert, dass langsamere Regex-Matches überprüft werden.	Schnelles Ausliefern statischer Assets und Sicherstellung, dass Asset-Verzeichnisse vorhersagbar behandelt werden.

4. Groß-/Kleinschreibung-beachtender regulärer Ausdruck (`~`)

Dies verwendet Perl Compatible Regular Expressions (PCRE) zum Matchen. Es ist leistungsstark, aber langsamer als Präfix-Matches. Der erste passende Regex-Block gewinnt.

Modifikator	Beispiel	Verhalten	Beste Verwendung
`~`	`location ~ \.php$`	Matcht jede URI, die auf `.php` endet.	Verarbeitung bestimmter Dateitypen (z. B. Weiterleitung von PHP-Skripten an PHP-FPM).

5. Groß-/Kleinschreibung-unabhängiger regulärer Ausdruck (`~*`)

Identisch zu ~, aber das Matchen ignoriert die Groß-/Kleinschreibung der URI.

Modifikator	Beispiel	Verhalten	Beste Verwendung
`~*`	`location ~* .(jpg	gif	png)$`

Die kritische Location-Verarbeitungsreihenfolge

Das Verständnis der Reihenfolge, in der Nginx Location Blöcke verarbeitet, ist entscheidend, um unerwartetes Verhalten zu vermeiden. Nginx liest Konfigurationsdateien nicht einfach von oben nach unten. Es verwendet eine strenge Hierarchie:

Exakter Match (=): Nginx überprüft zuerst alle exakten Match-Blöcke. Wenn ein Match gefunden wird, stoppt die Verarbeitung sofort und die Anfrage wird von diesem Block behandelt.
Längster Präfix-Kandidat: Nginx findet die längste passende Präfix-Location, einschließlich einfacher Präfix-Locations und ^~-Locations.
Regex-Überspringen für ^~: Wenn dieser beste Präfix-Match ^~ verwendet, verwendet Nginx ihn und überspringt Regex-Prüfungen.
Reguläre Ausdrücke (~ und ~*): Wenn der beste Präfix nicht ^~ war, überprüft Nginx Regex-Locations in der Reihenfolge, in der sie in der Konfigurationsdatei erscheinen. Der erste passende Regex-Block gewinnt.
Längster Standard-Präfix-Match: Wenn kein Regex-Match gewinnt, verwendet Nginx den längsten Präfix-Kandidaten, den es bereits gefunden hat. In vielen Konfigurationen ist location / der endgültige Fallback.

Aus diesem Grund ist ^~ /static/ üblich. Ohne ^~ kann ein späterer Regex wie location ~* \.(css|js)$ immer noch für /static/app.css gewinnen. Manchmal ist das in Ordnung. Manchmal umgeht es die Cache-Header, den Root-Pfad oder die Zugriffsregeln, die Sie für das gesamte /static/-Verzeichnis erwartet haben.

Praktische Konfigurationsszenarien

1. Priorisierung statischer Assets für die Leistung

Um sicherzustellen, dass Nginx statische Dateien direkt und schnell ausliefert und langsamere Regex-Prüfungen sowie unnötige Verarbeitung durch den Anwendungsserver verhindert, verwenden Sie den ^~-Modifikator.

server {
    listen 80;
    server_name myapp.com;

    # 1. Exakter Match für die Hauptseite (höchste Priorität)
    location = / {
        proxy_pass http://backend_app_server;
    }

    # 2. Schnelle Behandlung für statische Assets, unter Umgehung von Regex-Prüfungen
    location ^~ /static/ {
        root /var/www/site;
        expires 30d;
    }

    # 3. Regulärer Ausdruck für gängige Mediendateien
    location ~* \.(gif|ico|css|js)$ {
        root /var/www/site;
        expires 7d;
    }

    # 4. Fallback für alle anderen dynamischen Anfragen
    location / {
        proxy_pass http://backend_app_server;
    }
}

2. Routing und Proxying von API-Traffic

Bei Verwendung von Nginx als Reverse-Proxy leiten Location Blöcke den Traffic an den richtigen Upstream-Anwendungsserver weiter.

location /api/v1/ {
    # Stellen Sie sicher, dass Nginx die Client-Verbindungseinstellungen respektiert
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;

    # Leiten Sie allen Traffic, der mit /api/v1/ beginnt, an den Backend-Dienst weiter
    proxy_pass http://api_backend_service/v1/;

    # Mit einer URI in proxy_pass ersetzt Nginx das passende Präfix.
    # /api/v1/users wird upstream zu /v1/users.
}

Dieses Verhalten des abschließenden Schrägstrichs ist es wert, getestet zu werden. Diese beiden Beispiele sind unterschiedlich:

location /api/ {
    proxy_pass http://api_backend;
}

location /api/ {
    proxy_pass http://api_backend/;
}

Die erste Form übergibt die ursprüngliche URI, einschließlich /api/..., an den Upstream. Die zweite Form ersetzt das gematchte /api/-Präfix durch /. Wenn Ihr Upstream nach einer kleinen Konfigurationsänderung plötzlich 404 zurückgibt, überprüfen Sie dies, bevor Sie der App die Schuld geben.

3. Schützen sensibler Verzeichnisse

Location Blöcke können verwendet werden, um den externen Zugriff auf sensible interne Verzeichnisse zu verweigern, wie Konfigurationsdateien oder versteckte Verzeichnisse wie .git.

# Zugriff auf Dateien verweigern, die mit einem Punkt beginnen (versteckte Dateien)
location ~ /\.(ht|svn|git) {
    deny all;
    return 404; # 404 statt 403 zurückgeben, um ihre Existenz nicht preiszugeben
}

# Zugriff auf bestimmte Konfigurationsverzeichnisse verweigern
location /app/config/ {
    deny all;
}

Für versteckte Dateien verwenden viele Teams eine breitere Verweigerungsregel:

location ~ /\.(?!well-known/) {
    deny all;
    return 404;
}

Die Ausnahme hält /.well-known/ für Dinge wie ACME HTTP-01-Zertifikatsherausforderungen verfügbar, während die meisten Dotfiles blockiert werden. Testen Sie dies sorgfältig, wenn Ihre Website andere legitime, mit einem Punkt beginnende Pfade bedient.

Sicherheitswarnung: Verwendung von alias vs. root

Beachten Sie bei der Konfiguration von Dateipfaden innerhalb eines Location Blocks den Unterschied zwischen root und alias.

root: Hängt die vollständige Request-URI an den definierten Pfad an. (z. B. location /images/ + root /data/ führt zu /data/images/filename.jpg)

alias: Ersetzt den gematchten Teil der URI durch den definierten Pfad. Dies ist oft notwendig, wenn der Location Block einen Regex verwendet oder einen Teil des Pfads entfernen muss, bevor die Datei ausgeliefert wird. (z. B. location /static/ + alias /opt/app/files/ führt zu /opt/app/files/filename.jpg)

4. Behandlung von abschließenden Schrägstrichen und Weiterleitungen

Es ist oft wünschenswert, eine konsistente URL-Struktur durchzusetzen, z. B. sicherzustellen, dass Verzeichnisse immer mit einem abschließenden Schrägstrich (/) enden.

# Erzwingen Sie einen abschließenden Schrägstrich für Verzeichnispfade, falls fehlend
location ~* /[a-z0-9\-_]+$ {
    # Wenn die URI auf eine Datei matcht, wird Nginx versuchen, sie auszuliefern. Wenn nicht, behandeln Sie sie als Verzeichnis.
    # Überprüfen Sie, ob die angeforderte URI einem Verzeichnis auf der Festplatte zugeordnet ist:
    if (-d $request_filename) {
        return 301 $uri/;
    }
}

Eine gute Methode zum Debuggen des Location-Routings

Wenn eine Anfrage am falschen Ort ankommt, reduzieren Sie das Problem auf eine URL und einen server-Block. Führen Sie nginx -T aus, um die vollständig gerenderte Konfiguration einschließlich eingebundener Dateien zu sehen, und suchen Sie dann nach jeder Location, die diese URI matchen könnte. Achten Sie besonders auf Regex-Blöcke, da ihre Reihenfolge in der Datei wichtig ist.

Überprüfen Sie bei statischen Dateien den Dateisystempfad, den Nginx aus root oder alias erstellen wird. Überprüfen Sie bei proxied Anfragen, ob proxy_pass einen URI-Teil nach dem Upstream-Namen enthält. Laden Sie dann erst neu, nachdem nginx -t bestanden hat.

Location Blöcke sind vorhersagbar, sobald Sie die Prioritätsregeln verinnerlicht haben, aber sie sind unnachgiebig, wenn eine Konfiguration durch Kopieren und Einfügen wächst. Verwenden Sie exakte Matches für kleine heiße Pfade, ^~ für Verzeichnisse, die die Regex-Behandlung umgehen sollen, Regex nur dort, wo Mustervergleiche wirklich benötigt werden, und einen einfachen location / als klaren Fallback.