Nginx Location Wildcard - So funktioniert URL-Matching wirklich

Bei URL-Matching in Nginx geht es selten um eine echte Platzhalter-Syntax im location-Block, sondern darum, Pfade sauber in Prefix- und Regex-Regeln zu übersetzen. Genau hier entsteht die Verwirrung rund um nginx location wildcard: In der Praxis lösen meist exakte Treffer, längste Präfixe und reguläre Ausdrücke das Problem, nicht ein frei platzierbares Sternchen. In diesem Artikel zeige ich, wie Nginx wirklich entscheidet, welche Regel greift, wann Regex sinnvoll ist und welche Fehler mir in Produktivsystemen am häufigsten begegnen.

Warum der Wildcard-Begriff bei location in die Irre führt

Die offizielle Nginx-Dokumentation beschreibt location nicht als Platzhalter-Mechanismus, sondern als Auswahl zwischen einem literalem Präfix und einem regulären Ausdruck. Das ist ein wichtiger Unterschied, weil viele aus anderen Systemen ein Sternchen als „beliebige Zeichenfolge“ erwarten und dann nach einer Syntax suchen, die es hier schlicht nicht gibt. In Nginx ist der saubere Gedanke deshalb nicht „Wie baue ich einen Wildcard-Block?“, sondern „Wie drücke ich das URL-Muster präzise aus?“

Der häufigste Denkfehler entsteht durch die Nähe zu server_name. Dort sind Wildcards an den Rändern eines Namens erlaubt, etwa für Subdomains; ein Sternchen darf nur am Anfang oder Ende stehen und nicht mitten im Namen. Im location-Block gilt das nicht, denn hier entscheidet Nginx über URI-Pfade, nicht über Hostnamen. Wer also eigentlich *.example.org abbilden will, ist im falschen Kontext unterwegs.

Für die Praxis heißt das: Ich arbeite in location-Blöcken mit klaren Prefixen oder mit Regex, wenn ein Muster wirklich variabel ist. Genau diese Trennung macht die Konfiguration später wartbar, und sie reduziert Überraschungen im Betrieb. Als Nächstes lohnt sich ein Blick auf die eigentliche Reihenfolge, in der Nginx eine passende Regel sucht.

So entscheidet Nginx, welche location greift

Nginx wertet die Anfrage nicht einfach von oben nach unten aus. Zuerst wird die URI normalisiert, also dekodiert und von Punkten, Doppel-Slashes und ähnlichen Sonderfällen bereinigt. Danach prüft Nginx exakte Treffer und Prefixe, und erst im nächsten Schritt folgen reguläre Ausdrücke in der Reihenfolge ihres Auftretens.

1. Exakter Treffer mit location = /pfad beendet die Suche sofort.
2. Prefix mit dem längsten passenden Pfad gewinnt zunächst intern.
3. ^~ stoppt die weitere Regex-Prüfung für diesen Prefix.
4. Regex mit ~ oder ~* wird in Konfigurationsreihenfolge getestet.
5. Wenn kein Regex passt, bleibt der zuvor gefundene Prefix aktiv.

Ein Detail wird dabei oft übersehen: Nginx bewertet nur den URI-Teil der Anfrage, nicht den Query-String. /produkt?id=12 und /produkt?id=99 landen also im gleichen Matching, weil die Parameter für location keine Rolle spielen. Genau deshalb sind Pfadregeln und Applikationslogik zwei verschiedene Ebenen.

In vielen Konfigurationen ist diese Reihenfolge der entscheidende Hebel, nicht ein „Wildcard“-Trick. Sobald man sie verstanden hat, wird auch klar, wann Prefixe reichen und wann Regex den besseren Job macht.

Prefix, regex oder named location

Ich entscheide in Projekten fast immer nach demselben Muster: möglichst wenig Magie, möglichst viel Klarheit. Die folgende Gegenüberstellung zeigt, welches Werkzeug in welchem Fall sinnvoll ist.

Wenn ich schnell entscheiden muss, nehme ich fast immer den einfachsten Mechanismus, der das Problem sauber löst. Prefixe sind für die meisten Webserver-Konfigurationen die beste Default-Wahl, Regex setze ich nur dort ein, wo ich wirklich Variabilität brauche. Das spart nicht nur Rechenzeit, sondern vor allem spätere Fehlersuche.

Die eigentliche Kunst besteht also nicht darin, möglichst viele Regeln zu bauen, sondern die richtige Kategorie zu wählen. Genau das zeigt sich besonders gut an konkreten URL-Mustern.

Praktische Beispiele für typische URL-Muster

In realen Setups tauchen immer wieder dieselben Muster auf: statische Assets, API-Präfixe, Dateiendungen und Sonderrouten für Monitoring oder Fehlerbehandlung. Die folgenden Beispiele zeigen, wie ich solche Fälle in Nginx typischerweise abbilden würde.

Statische Assets sauber schützen

location ^~ /assets/ {
    expires 30d;
    add_header Cache-Control "public";
}

Diese Form ist für CSS, JS, Bilder oder Fonts sehr praktisch. Das ^~ verhindert, dass später definierte Regex-Regeln aus Versehen an den Asset-Pfad heranrücken, was gerade in größeren Konfigurationen ein echter Stabilitätsgewinn ist.

API-Versionen oder strukturierte Pfade

location ~ ^/api/v[0-9]+/ {
    proxy_pass http://backend;
}

Hier braucht man Variable im Pfad, aber kein freies Muster über den gesamten URI. Der Regex bleibt eng genug, um nicht zu viel zu fassen, und zugleich flexibel genug für Versionen wie /api/v1/ oder /api/v2/. Genau solche Regeln sind mit einem einfachen Prefix nicht mehr sauber lösbar.

Dateiendungen gezielt behandeln

location ~* \.(css|js|png|jpg|jpeg|svg|webp)$ {
    access_log off;
    expires 7d;
}

Hier ist ~* oft sinnvoll, wenn die Endung tolerant gematcht werden darf. Ich setze das aber bewusst sparsam ein, weil Groß- und Kleinschreibung im Dateisystem und in der URL-Logik nicht immer gleich behandelt werden sollten. Für saubere Produktivsysteme ist „möglichst eindeutig“ meist besser als „möglichst tolerant“.

Lesen Sie auch: Nginx Plugin nicht installiert? So löst du den Certbot-Fehler!

Sonderrouten für Health Checks oder Fallbacks

location = /healthz {
    return 200 "ok";
}

location / {
    try_files $uri $uri/ @fallback;
}

location @fallback {
    proxy_pass http://backend;
}

Diese Kombination ist robust, weil sie Sonderfälle klar vom normalen Request-Flow trennt. Ein exakter Health-Check ist für Load Balancer und Uptime-Monitoring ideal, und die Named Location hält den Fallback intern, statt den Client unnötig umzuleiten.

Diese Beispiele wirken banal, sind in der Praxis aber genau deshalb wertvoll: Sie zeigen, dass gute Nginx-Konfiguration nicht von Zauberregeln lebt, sondern von klaren, eng gefassten Mustern. Im nächsten Schritt geht es um die Stellen, an denen diese Klarheit typischerweise verloren geht.

Die häufigsten Fehler bei wildcard-artigen Regeln

Die meisten Probleme entstehen nicht durch Nginx selbst, sondern durch falsche Erwartungen an das Matching. Ich sehe dabei immer wieder dieselben Muster.

• Ein Sternchen im location erwartet: Das funktioniert nicht wie bei Hostnamen und führt meist direkt zu Frust.
• Zu breite Regex: Ein unpräziser Ausdruck trifft mehr URIs als geplant und ist später schwer zu debuggen.
• Falsche Reihenfolge angenommen: Wer die Matching-Logik von oben nach unten liest, übersieht die echte Priorität.
• ^~ falsch eingesetzt: Das schützt nur vor Regex, nicht vor einem falsch formulierten Prefix.
• Query-Parameter mit URI verwechselt: Die Parameter gehören nicht in die Location-Entscheidung.
• server_name und location vermengt: Hostname-Matching und Pfad-Matching sind zwei verschiedene Ebenen.

Ein besonders teurer Fehler ist für mich die Annahme, dass man mit Regex immer „mehr kann“. Das stimmt formal, aber nicht operativ. Jede zusätzliche Flexibilität kostet Lesbarkeit, und sobald mehrere Kollegen an der Konfiguration arbeiten, wird aus einem kleinen Regex schnell eine fragile Sonderlösung.

Bei Unklarheiten teste ich deshalb zuerst mit einem minimalen Konfigurationsausschnitt und prüfe dann, welcher Block wirklich greift. So lässt sich schnell erkennen, ob das Problem im Matching, in der Reihenfolge oder einfach im falschen Regeltyp liegt. Genau daraus ergibt sich auch meine Regel für wartbare Konfigurationen.

So halte ich Nginx-Regeln wartbar und schnell

Wenn ich eine Konfiguration langfristig sauber halten will, versuche ich drei Dinge konsequent: so wenig Regex wie möglich, so viel Spezifität wie nötig und so wenig Überraschung wie technisch vertretbar. Das klingt unspektakulär, ist aber im Betrieb meist der entscheidende Unterschied zwischen „läuft“ und „läuft nachvollziehbar“.

• Ich beginne mit dem engsten Prefix und greife nur dann zu Regex, wenn der Pfad wirklich variabel ist.
• Ich sichere kritische Bereiche mit ^~, wenn dort keine Regex-Regel dazwischenfunken darf.
• Ich halte Regex kurz und lesbar, statt mehrere Sonderfälle in einen einzigen Ausdruck zu pressen.
• Ich trenne Hostnamenlogik von URI-Logik, damit die Zuständigkeit klar bleibt.
• Ich prüfe Änderungen mit nginx -t, bevor sie in Produktion gehen.

Ein weiterer praktischer Punkt ist Konsistenz. Wenn eine Anwendung unter /app/ läuft, sollte nicht parallel noch /app, /application oder ein halb passender Regex existieren, nur weil es „auch irgendwie funktioniert“. Solche Parallelwelten sind der Anfang von schwer reproduzierbaren Fehlern.

Wer Nginx in größeren Umgebungen betreibt, profitiert außerdem von klaren Namensmustern und kurzen Kommentaren direkt an den Sonderfällen. Nicht jede Regel braucht Erklärung, aber jede Ausnahme sollte sofort erkennbar machen, warum sie existiert. Genau das macht spätere Anpassungen deutlich günstiger.

Das einfache Muster, das in den meisten Setups trägt

Für die Praxis bleibt für mich eine einfache Reihenfolge am verlässlichsten: erst den URI sauber mit einem Prefix oder einem exakten Treffer abfangen, dann nur dort mit Regex arbeiten, wo das Muster wirklich variabel ist, und Hostname-Wildcards nie mit Pfadregeln verwechseln. So löst man das eigentliche Problem hinter nginx location wildcard, ohne sich an einer Syntax festzuhalten, die Nginx in diesem Kontext gar nicht anbietet.

Wenn ich eine bestehende Konfiguration prüfe, suche ich daher zuerst nach unnötig breiten Regex, danach nach fehlenden ^~-Schutzschichten und erst am Ende nach echten Spezialfällen. In den meisten Webserver-Setups reicht diese Reihenfolge schon aus, um Matching verständlicher, schneller und deutlich robuster zu machen.