Skip to main content

NGINX Alias vs. Root: Schluss mit der Verwirrung ein für alle Mal

Dieser Artikel ist eine Übersetzung des englischen Originals.


Die Verwirrung zwischen den NGINX-Direktiven alias und root hat mehr kaputte Konfigurationen verursacht als fast jedes andere NGINX-Konzept. Wenn Sie jemals Stunden damit verbracht haben, zu debuggen, warum Ihre statischen Dateien 404-Fehler zurückgeben, oder sich gefragt haben, warum Ihre scheinbar völlig korrekte Konfiguration nicht funktioniert, sind Sie nicht allein.

In diesem Leitfaden erfahren Sie genau, wie sich NGINX alias vs. root auf Implementierungsebene unterscheidet. Wir untersuchen, wie NGINX Dateipfade intern konstruiert, wann welche Direktive zu verwenden ist und die kritischen Regeln für abschließende Schrägstriche, über die selbst erfahrene Administratoren stolpern. Jede Konfiguration in diesem Artikel wurde auf Rocky Linux 10 mit NGINX 1.26 getestet.

Wie NGINX Dateipfade konstruiert

Bevor wir den Unterschied zwischen alias und root verstehen können, müssen wir verstehen, wie NGINX eine URL auf eine Datei auf der Festplatte abbildet. Dieser Pfadaufbau erfolgt in der Funktion ngx_http_map_uri_to_path() tief im Kernmodul von NGINX.

Wenn eine Anfrage eingeht, muss NGINX die angeforderte URI in einen tatsächlichen Dateisystempfad übersetzen. Gemäß der offiziellen NGINX-Dokumentation unterscheidet sich die Formel für den Pfadaufbau zwischen root und alias:

Mit root:

filesystem_path = root + full_URI

Mit alias:

filesystem_path = alias + (URI - location_match)

Dieser grundlegende Unterschied ist die Quelle aller Verwirrung rund um NGINX alias vs. root. Sehen wir ihn uns in der Praxis an.

Die root-Direktive: Anhängen der vollständigen URI

Die Direktive root gibt ein Basisverzeichnis an, und NGINX hängt die gesamte Anfrage-URI daran an. Dies ist die einfachere der beiden Direktiven und sollte Ihre Standardwahl sein, wenn Sie zwischen NGINX alias vs. root wählen.

server {
    listen 80;
    server_name example.com;

    location /images {
        root /var/www/html;
    }
}

Wenn eine Anfrage für /images/logo.png eingeht, konstruiert NGINX den Pfad wie folgt:

/var/www/html + /images/logo.png = /var/www/html/images/logo.png

Die vollständige URI /images/logo.png wird an den root-Pfad angehängt. Das bedeutet, dass Ihre Verzeichnisstruktur den Ordner /images innerhalb von /var/www/html enthalten muss.

Platzierung der root-Direktive

Die Direktive root kann im Kontext http, server oder location platziert werden. Sie wird üblicherweise auf Serverebene platziert und von allen Locations geerbt:

server {
    listen 80;
    root /var/www/html;

    location /images {
        # Inherits root /var/www/html
        # /images/logo.png -> /var/www/html/images/logo.png
    }

    location /css {
        # Inherits root /var/www/html
        # /css/style.css -> /var/www/html/css/style.css
    }

    location /uploads {
        # Override root for this location
        root /var/www/uploads;
        # /uploads/file.pdf -> /var/www/uploads/uploads/file.pdf
    }
}

Beachten Sie den letzten location-Block: Wenn Sie root in einer Location überschreiben, wird der Location-Pfad trotzdem angehängt. Dies überrascht viele Administratoren.

Die alias-Direktive: Ersetzen des Location-Treffers

Die Direktive alias ersetzt den übereinstimmenden Location-Teil der URI durch den angegebenen Pfad. Dies ist der entscheidende Unterschied im Vergleich NGINX alias vs. root.

server {
    listen 80;
    server_name example.com;

    location /images {
        alias /var/www/static/images;
    }
}

Wenn eine Anfrage für /images/logo.png eingeht, konstruiert NGINX den Pfad wie folgt:

/var/www/static/images + /logo.png = /var/www/static/images/logo.png

NGINX entfernt /images aus der URI und hängt nur den verbleibenden Teil /logo.png an den alias-Pfad an. Der Location-Treffer wird ersetzt, nicht angehängt.

Wann alias verwendet werden sollte

Verwenden Sie alias, wenn:

  • Sie Dateien aus einem Verzeichnis bereitstellen möchten, das nicht dem URL-Pfad entspricht
  • Sie ein URL-Präfix einem völlig anderen Speicherort auf der Festplatte zuordnen
  • Sie statische Dateien von außerhalb Ihres Haupt-Dokumentstammverzeichnisses bereitstellen müssen
# Serve files from /srv/downloads when requesting /files/
location /files/ {
    alias /srv/downloads/;
}

# Serve static assets from a CDN directory
location /static/ {
    alias /var/cache/cdn/assets/;
}

# Serve user uploads from a separate partition
location /uploads/ {
    alias /mnt/storage/user-uploads/;
}

Einschränkungen von alias

Die Direktive alias unterliegt mehr Einschränkungen als root:

  1. Kann nicht in benannten Locations verwendet werden: Benannte Locations (jene, die mit @ beginnen) können alias nicht verwenden
  2. Kann nicht mit bestimmten Rewrites verwendet werden: Wenn die URI durch ein Rewrite geändert wird, kann alias unerwartete Ergebnisse liefern
  3. Sie ist nur im location-Kontext gültig: Anders als root kann alias nicht in http– oder server-Blöcken platziert werden

Die kritische Regel für abschließende Schrägstriche

Der abschließende Schrägstrich ist die Ursache der meisten Verwirrung rund um NGINX alias vs. root. Ein Fehler hier führt zu 404-Fehlern, deren Debugging Stunden dauern kann.

Die Regel für alias

Bei Verwendung von alias müssen die abschließenden Schrägstriche zwischen der Location und dem alias-Pfad übereinstimmen:

Korrekt:

location /files/ {
    alias /srv/downloads/;
}

Korrekt:

location /files {
    alias /srv/downloads;
}

Falsch – führt zu Fehlern:

location /files/ {
    alias /srv/downloads;  # Missing trailing slash
}

Sehen wir uns an, warum die falsche Konfiguration fehlschlägt. Mit location /files/ und alias /srv/downloads (ohne abschließenden Schrägstrich):

  • Request: /files/report.pdf
  • Location match: /files/
  • Remaining URI: report.pdf (note: no leading slash)
  • Path construction: /srv/downloads + report.pdf = /srv/downloadsreport.pdf

Der fehlende Schrägstrich führt dazu, dass der Pfad ohne Trennzeichen zusammengefügt wird, was zu einem nicht existierenden Pfad führt.

Warum root dieses Problem nicht hat

Bei root wird immer die vollständige URI angehängt, sodass die Schrägstrich-Situation konsistent ist:

location /files {
    root /srv;
}
# /files/report.pdf -> /srv/files/report.pdf (correct)

location /files/ {
    root /srv;
}
# /files/report.pdf -> /srv/files/report.pdf (correct)

Die URI beginnt immer mit einem Schrägstrich, sodass sie sich auf natürliche Weise vom root-Pfad trennt.

Praktischer Rat

Um Probleme mit abschließenden Schrägstrichen bei alias zu vermeiden, folgen Sie immer diesem Muster:

location /prefix/ {
    alias /path/to/directory/;
}

Sowohl die Location als auch der alias enden mit Schrägstrichen. Dies ist der sicherste und lesbarste Ansatz.

NGINX alias vs. root mit try_files

Die Direktive try_files verhält sich bei alias und root unterschiedlich, und das Verständnis dieser Interaktion ist entscheidend für die Bereitstellung statischer Dateien mit Fallbacks.

try_files mit root

server {
    listen 80;
    root /var/www/html;

    location /assets/ {
        try_files $uri $uri/ =404;
    }
}

Bei einer Anfrage für /assets/style.css:

  1. NGINX constructs: /var/www/html/assets/style.css
  2. If not found, tries: /var/www/html/assets/style.css/
  3. If not found, returns 404

Dies funktioniert wie erwartet, da root die vollständige URI anhängt.

try_files mit alias

server {
    listen 80;

    location /assets/ {
        alias /srv/static-files/;
        try_files $uri $uri/ =404;
    }
}

Bei einer Anfrage für /assets/style.css:

  1. NGINX constructs: /srv/static-files/style.css
  2. If not found, tries: /srv/static-files/style.css/
  3. If not found, returns 404

Der entscheidende Unterschied besteht darin, dass try_files bei alias korrekt den aliasierten Pfad verwendet. Das Präfix /assets/ wird beim Aufbau des Dateisystempfads entfernt.

Häufiger try_files-Fehler

Ein häufiger Fehler ist die Verwendung von alias, wenn Sie root verwenden sollten:

# Wrong: trying to serve /assets/* from /var/www/html/assets/
location /assets/ {
    alias /var/www/html/assets/;
    try_files $uri $uri/ =404;
}

# Better: use root when the directory structure matches
location /assets/ {
    root /var/www/html;
    try_files $uri $uri/ =404;
}

Wenn der URL-Pfad der Dateisystemstruktur entspricht, bevorzugen Sie aus Einfachheitsgründen root.

Verwendung von alias mit Regex-Locations

Wenn Sie alias innerhalb einer Regex-Location verwenden, müssen Sie Capture-Gruppen verwenden. NGINX benötigt dies, um zu wissen, welcher Teil der URI ersetzt werden soll.

Falsch (verursacht Fehler)

location ~ ^/images/ {
    alias /srv/static/images/;  # Does not work correctly with regex
}

Korrekt (mit Capture-Gruppen)

location ~ ^/users/(d+)/avatar.jpg$ {
    alias /srv/avatars/$1.jpg;
}

In diesem Beispiel:
– Anfrage: /users/123/avatar.jpg
– Capture-Gruppe $1: 123
– Aufgelöster Pfad: /srv/avatars/123.jpg

Der Regex erfasst die Benutzer-ID, und alias verwendet sie, um den korrekten Pfad zu konstruieren.

Mehrere Capture-Gruppen

location ~ ^/galleries/([a-z]+)/(d+).jpg$ {
    alias /srv/images/$1/photo_$2.jpg;
}
  • Request: /galleries/summer/42.jpg
  • $1: summer
  • $2: 42
  • Resolved path: /srv/images/summer/photo_42.jpg

Verhalten bei automatischer Verzeichnisweiterleitung

Wenn eine Anfrage einem Verzeichnis ohne abschließenden Schrägstrich entspricht, kann NGINX automatisch weiterleiten, um den Schrägstrich hinzuzufügen. Dieses Verhalten unterscheidet sich geringfügig zwischen root und alias.

Mit root

location /docs {
    root /var/www;
    index index.html;
}

Anfrage an /docs (ohne abschließenden Schrägstrich):
1. NGINX stellt fest, dass /var/www/docs ein Verzeichnis ist
2. Gibt eine 301-Weiterleitung an /docs/ zurück
3. Eine neue Anfrage an /docs/ liefert /var/www/docs/index.html

Mit alias

location /documentation/ {
    alias /var/www/docs/;
    index index.html;
}

Anfrage an /documentation (ohne abschließenden Schrägstrich):
1. Entspricht nicht location /documentation/
2. Fällt auf eine andere Location zurück oder gibt 404 zurück

Um sowohl mit als auch ohne abschließenden Schrägstrich zu behandeln:

location /documentation {
    alias /var/www/docs;
    index index.html;
}

location /documentation/ {
    alias /var/www/docs/;
    index index.html;
}

Oder verwenden Sie ein Rewrite:

location /documentation {
    rewrite ^/documentation$ /documentation/ permanent;
}

location /documentation/ {
    alias /var/www/docs/;
    index index.html;
}

NGINX alias vs. root: Kurzreferenz

Aspekt root alias
Pfadformel root + full_URI alias + (URI – location)
Gültige Kontexte http, server, location Siehe location
Abschließender Schrägstrich Nicht kritisch Muss mit der Location übereinstimmen
Regex-Locations Funktioniert ohne Änderungen Erfordert Capture-Gruppen
Benannte Locations Unterstützt Nicht unterstützt
Mit try_files Unkompliziert Funktioniert, aber Vorsicht
Standardwahl Ja Nur bei Bedarf

Wann root vs. alias verwendet werden sollte

Verwenden Sie root, wenn:

  • DER URL-Pfad Ihrer Verzeichnisstruktur entspricht
  • Sie eine einfache, wartbare Konfiguration wünschen
  • Sie einen Basispfad auf Serverebene festlegen
  • Sie benannte Locations verwenden müssen

Verwenden Sie alias, wenn:

  • DER URL-Pfad nicht dem Dateisystempfad entspricht
  • Sie Dateien von einem völlig anderen Speicherort bereitstellen
  • Sie ein URL-Präfix einem Verzeichnis mit einem anderen Namen zuordnen müssen
  • Sie mehrere Verzeichnisse unter verschiedenen URL-Präfixen zusammenfassen

Testen Ihrer Konfiguration

Testen Sie Ihre NGINX-Konfiguration immer vor der Bereitstellung:

# Verify configuration syntax
nginx -t

# Test a specific file request
curl -I http://localhost/images/logo.png

# Check the actual file path in error logs (enable debug logging)
# Add to nginx.conf: error_log /var/log/nginx/error.log debug;
tail -f /var/log/nginx/error.log | grep "http filename"

Installation von NGINX

Auf RHEL-basierten Systemen (Rocky Linux, AlmaLinux, CentOS):

dnf install nginx
systemctl enable --now nginx

Das statische Modul, das sowohl root als auch alias verarbeitet, ist standardmäßig einkompiliert.

Fazit

Der Unterschied zwischen NGINX alias und root läuft auf ein Schlüsselkonzept hinaus: root hängt die gesamte URI an den Pfad an, während alias den Location-Treffer durch den angegebenen Pfad ersetzt.

Wichtigste Erkenntnisse:

  • Standardmäßig root verwenden: Verwenden Sie root, es sei denn, Sie müssen URLs ausdrücklich Verzeichnissen mit anderen Namen zuordnen
  • Abschließende Schrägstriche bei alias abgleichen: Sowohl die Location als auch der alias-Pfad sollten entweder abschließende Schrägstriche haben oder nicht
  • Capture-Gruppen mit Regex verwenden: Wenn Sie alias mit Regex-Locations kombinieren, müssen Sie Capture-Gruppen verwenden
  • Testen Sie Ihre Pfade: Aktivieren Sie beim Debuggen die Debug-Protokollierung, um genau zu sehen, wie NGINX Dateipfade konstruiert

Das Verständnis, wie NGINX intern Dateipfade konstruiert, beseitigt das Rätselraten aus Ihren Konfigurationen. Die Pfadformel sagt Ihnen genau, was passieren wird, und übereinstimmende abschließende Schrägstriche verhindern die häufigsten Fehler.

Für verwandte NGINX-Konfigurationsthemen lesen Sie unsere Leitfäden zu NGINX location priority, NGINX rewrite rules und tuning proxy_buffer_size.

Routing heute ist Sicherheit morgen. Eine falsch sortierte location oder ein Regex, der falsch greift, wird zu einem offenen Pfad. GetPageSpeed Amplify führt geplante gixy-Scans auf jedem Host aus und verknüpft die Ergebnisse mit Live-NGINX-Laufzeitmetriken. Drop-in-kompatibel mit dem veralteten nginx-amplify-agent (EOL Januar 2026).