Skip to main content

NGINX map-Direktive: Leitfaden für bedingte Variablen

Dieser Artikel ist eine Übersetzung des englischen Originals.


Die NGINX-Direktive map ist eine der leistungsfähigsten, aber am wenigsten genutzten Funktionen in der NGINX-Konfiguration. Sie ermöglicht es Ihnen, Variablen zu erstellen, deren Werte von den Werten anderer Variablen abhängen, und so komplexe bedingte Logik ohne den Leistungsnachteil mehrerer if-Anweisungen umzusetzen. Dieser Leitfaden behandelt alles, was Sie über die NGINX map-Direktive wissen müssen – von der grundlegenden Syntax bis zu fortgeschrittenen praxisnahen Anwendungen.

Was ist die NGINX map-Direktive?

Die Direktive map erstellt eine neue Variable, deren Wert durch Zuordnung des Werts einer Quellvariablen zu einer Reihe von Mustern bestimmt wird. Betrachten Sie sie als eine hochoptimierte switch-Anweisung oder Nachschlagetabelle, die während der Anfrageverarbeitung mit nahezu null Kosten ausgeführt wird.

Die grundlegende Syntax lautet:

map $source_variable $new_variable {
    default     default_value;
    pattern1    value1;
    pattern2    value2;
}

Der map-Block muss im http-Kontext platziert werden, außerhalb jedes server-Blocks. Der Grund dafür ist, dass NGINX die Map beim Laden der Konfiguration in eine effiziente Hash-Tabelle kompiliert, nicht während der Anfrageverarbeitung.

Warum die map-Direktive statt if-Anweisungen verwenden?

Viele NGINX-Administratoren greifen zu if-Anweisungen, wenn sie bedingte Logik benötigen. Das Prinzip if is evil in NGINX hat jedoch seinen guten Grund. Die Direktive map bietet mehrere Vorteile:

Leistung: Maps werden beim Laden der Konfiguration in Hash-Tabellen kompiliert. Nachschlagevorgänge sind bei exakten Übereinstimmungen O(1), was sie unabhängig von der Anzahl der Einträge extrem schnell macht.

Sauberere Konfiguration: Statt verschachtelter if-Blöcke, die über Ihre Konfiguration verstreut sind, zentralisieren Maps die bedingte Logik an einer Stelle.

Wiederverwendbarkeit: Eine durch eine Map definierte Variable kann überall in Ihrer Konfiguration verwendet werden – in server-Blöcken, location-Blöcken, Log-Formaten und mehr.

Sicherheit: Anders als if-Anweisungen können Maps kein unerwartetes Verhalten mit anderen Direktiven verursachen. Weitere Informationen zur NGINX-Header-Konfiguration finden Sie in unserem Leitfaden zu Den Fallstricken von add_header in NGINX.

Grundlegende Beispiele für die map-Direktive

ERKENNUNG MOBILER GERÄTE

Eine der häufigsten Anwendungen der map-Direktive ist die Geräteerkennung anhand des User-Agent:

map $http_user_agent $is_mobile {
    default         0;
    "~*mobile"      1;
    "~*android"     1;
    "~*iphone"      1;
    "~*ipad"        1;
}

Das Präfix ~* kennzeichnet eine Übereinstimmung mit einem regulären Ausdruck ohne Beachtung der Groß-/Kleinschreibung. Anschließend können Sie $is_mobile überall in Ihrer Konfiguration verwenden:

server {
    listen 80;
    server_name example.com;

    location / {
        if ($is_mobile) {
            return 301 https://m.example.com$request_uri;
        }
        # Regular processing
    }
}

Backend-Server basierend auf dem Hostnamen festlegen

Sie können Maps verwenden, um Anfragen basierend auf dem eingehenden Hostnamen an verschiedene Backend-Server weiterzuleiten:

map $host $backend_pool {
    default             "default_backend";
    example.com         "production";
    staging.example.com "staging";
    dev.example.com     "development";
}

upstream production {
    server 10.0.1.10:8080;
    server 10.0.1.11:8080;
}

upstream staging {
    server 10.0.2.10:8080;
}

upstream development {
    server 10.0.3.10:8080;
}

server {
    listen 80;
    server_name _;

    location / {
        proxy_pass http://$backend_pool;
    }
}

Das Musterabgleichsverhalten von map verstehen

Die NGINX map-Direktive unterstützt mehrere Methoden des Musterabgleichs, die in einer bestimmten Reihenfolge ausgewertet werden:

1. Exakte Zeichenfolgenübereinstimmungen

Die einfachste Form stimmt exakt mit der Quellvariablen überein:

map $uri $cache_zone {
    default         "default_zone";
    /api/users      "users_cache";
    /api/products   "products_cache";
}

2. Muster für reguläre Ausdrücke

Stellen Sie einem Muster ~ für einen regulären Ausdruck mit Beachtung der Groß-/Kleinschreibung oder ~* für einen ohne Beachtung der Groß-/Kleinschreibung voran:

map $uri $cache_duration {
    default                     "1h";
    "~^/api/v([0-9]+)/"        "5m";
    "~*[.](jpg|jpeg|png|gif)$"  "30d";
    "~*[.](css|js)$"            "7d";
}

Reguläre Ausdrücke können Erfassungsgruppen enthalten. Die erfassten Werte sind als $1, $2 usw. innerhalb des Map-Werts verfügbar:

map $uri $api_version {
    default                 "v1";
    "~^/api/v([0-9]+)/"     "v$1";
}

Weitere Details zu NGINX-Mustern finden Sie in unserem Artikel zu NGINX location priority.

3. Wildcard-Muster für Hostnamen

Wenn der Parameter hostnames angegeben ist, aktiviert NGINX einen speziellen Wildcard-Abgleich, der für Domänennamen optimiert ist:

map $host $site_tier {
    hostnames;
    default         "unknown";
    example.com     "main";
    *.example.com   "subdomain";
    .example.org    "wildcard";
    mail.*          "mail_server";
}

Der Parameter hostnames aktiviert zwei Wildcard-Typen:

  • *.example.com – stimmt mit jeder Subdomain überein (api.example.com, www.example.com)
  • .example.com – dasselbe wie oben, Kurzschreibweise
  • mail.* – stimmt mit mail.example.com, mail.example.org usw. überein

NGINX speichert diese Wildcards in optimierten Hash-Tabellen, wodurch Nachschlagevorgänge selbst bei Tausenden von Einträgen effizient bleiben.

Priorität des Musterabgleichs

Wenn mehrere Muster übereinstimmen könnten, wertet NGINX sie in dieser Reihenfolge aus:

  1. Exakte Zeichenfolgenübereinstimmung (höchste Priorität)
  2. Präfix-Wildcard (*.example.com)
  3. Suffix-Wildcard (www.*)
  4. Reguläre Ausdrücke (in der Reihenfolge ihres Auftretens)
  5. Standardwert (niedrigste Priorität)

Die erste Übereinstimmung gewinnt. Bei regulären Ausdrücken spielt die Reihenfolge eine Rolle – frühere Muster haben Vorrang.

DER Parameter default

Jede Map sollte einen default-Wert enthalten. Dieser Wert wird verwendet, wenn kein Muster übereinstimmt:

map $request_method $is_write_method {
    default     0;
    POST        1;
    PUT         1;
    PATCH       1;
    DELETE      1;
}

Sicherheitswarnung: Das Weglassen des Standardwerts kann zu leeren Variablenwerten führen und möglicherweise Sicherheitskontrollen umgehen. Sicherheitstools wie Gixy prüfen gezielt auf Maps ohne Standardwerte und melden sie als Probleme mittlerer Schwere.

DER Parameter volatile

Standardmäßig speichert NGINX Map-Ergebnisse pro Anfrage zwischen. Der Parameter volatile deaktiviert diese Zwischenspeicherung:

map $arg_timestamp $cache_buster {
    volatile;
    default     "";
    "~.+"       $arg_timestamp;
}

Verwenden Sie volatile, wenn:
– sich die Quellvariable während der Anfrageverarbeitung ändert
– Sie bei jedem Zugriff auf die Variable eine neue Auswertung benötigen
– das Map-Ergebnis von Variablen abhängt, die von anderen Modulen geändert werden können

In den meisten Fällen sollten Sie volatile nicht verwenden, da das standardmäßige Zwischenspeicherungsverhalten die Leistung verbessert.

DIE include-Direktive innerhalb von Maps

Bei großen Maps können Sie Einträge in separate Dateien aufteilen:

map $http_user_agent $is_bot {
    default     0;
    include     /etc/nginx/maps/known-bots.map;
}

Die eingebundene Datei enthält einfache Map-Einträge:

# /etc/nginx/maps/known-bots.map
"~*googlebot"       1;
"~*bingbot"         1;
"~*yandexbot"       1;
"~*baiduspider"     1;
"~*duckduckbot"     1;

Dieser Ansatz eignet sich hervorragend für die Pflege großer Blocklisten oder Whitelists, ohne Ihre Hauptkonfiguration zu überladen.

Optimierung von Map-Hash-Tabellen

Für die meisten Konfigurationen funktionieren die Standardeinstellungen von NGINX einwandfrei. Sie müssen die Hash-Einstellungen nur dann anpassen, wenn NGINX Warnungen oder Fehler zu Map-Hash-Tabellen ausgibt.

Zwei Direktiven steuern Map-Hash-Tabellen:

  • map_hash_max_size – Maximale Anzahl von Buckets (Standard: 2048)
  • map_hash_bucket_size – Größe jedes Buckets (Standard: CPU-Cache-Zeile, üblicherweise 64)

Wichtig: Wenn Sie von den Standardwerten abweichende Werte benötigen, müssen diese Direktiven vor allen map-Blöcken in Ihrer Konfiguration erscheinen. Wenn Sie sie nach einem Map-Block platzieren, treten Fehler auf.

http {
    # Hash directives MUST come before map blocks
    map_hash_max_size 8192;

    map $uri $redirect_target {
        # ... entries ...
    }
}

Wenn Sie Warnungen sehen: Wenn NGINX meldet „could not build optimal map_hash“, haben Sie viele Einträge. Erhöhen Sie map_hash_max_size.

Wenn Sie Fehler sehen: Wenn NGINX meldet „increase map_hash_bucket_size“, haben Sie sehr lange Schlüssel (über 46 Zeichen). Erhöhen Sie map_hash_bucket_size auf 128.

Eine ausführliche Erklärung des Hash-Algorithmus, der Schlüssellängenlimits, getesteter Schwellenwerte und des vollständigen Optimierungsablaufs finden Sie in unserem umfassenden Leitfaden: NGINX Map Hash Tuning.

Praxisnahe Anwendungsfälle der map-Direktive

Rate Limiting mit Maps

Erstellen Sie mit Maps ausgefeilte Rate-Limiting-Regeln:

# Determine rate limit key based on request type
map $request_uri $rate_limit_key {
    default             $binary_remote_addr;
    "~^/api/"           $binary_remote_addr$uri;
    "~^/login"          $binary_remote_addr;
    "~^/static/"        "";
}

# Whitelist certain IPs from rate limiting
map $remote_addr $is_whitelisted {
    default             0;
    127.0.0.1           1;
    "~^10[.]"           1;
    "~^192[.]168[.]"    1;
}

# Final rate limit key (empty = no limiting)
map $is_whitelisted $final_rate_key {
    default     $rate_limit_key;
    1           "";
}

limit_req_zone $final_rate_key zone=api_limit:10m rate=10r/s;

server {
    listen 80;

    location /api/ {
        limit_req zone=api_limit burst=20 nodelay;
        proxy_pass http://backend;
    }
}

Diese Konfiguration:
– wendet unterschiedliche Rate-Limiting-Regeln auf verschiedene URL-Muster an
– nimmt IP-Adressen auf der Whitelist vollständig aus
– überspringt das Rate Limiting für statische Dateien
– verwendet ein kaskadierendes Map-Muster für komplexe Logik

URL-Weiterleitungen mit Maps

Behandeln Sie Weiterleitungen von Legacy-URLs effizient:

map $uri $redirect_target {
    default                     "";
    /old-page                   /new-page;
    /legacy/products            /shop/products;
    "~^/blog/([0-9]+)/(.*)$"   /articles/$1/$2;
    /discontinued               https://archive.example.com/discontinued;
}

server {
    listen 80;
    server_name example.com;

    if ($redirect_target) {
        return 301 $redirect_target;
    }

    # Normal processing continues if no redirect
    location / {
        try_files $uri $uri/ /index.php?$args;
    }
}

Dieses Muster verarbeitet Hunderte von Weiterleitungen mit minimaler Konfiguration und optimaler Leistung.

Dynamische CORS-Konfiguration

Implementieren Sie sicheres CORS mit Maps:

map $http_origin $cors_origin {
    default                             "";
    "~^https://(www[.])?example[.]com$" $http_origin;
    "~^https://.*[.]example[.]com$"     $http_origin;
}

map $cors_origin $cors_methods {
    default     "";
    "~.+"       "GET, POST, PUT, DELETE, OPTIONS";
}

map $cors_origin $cors_headers {
    default     "";
    "~.+"       "Content-Type, Authorization, X-Requested-With";
}

map $cors_origin $cors_credentials {
    default     "";
    "~.+"       "true";
}

server {
    listen 443 ssl;
    server_name api.example.com;

    add_header Access-Control-Allow-Origin $cors_origin always;
    add_header Access-Control-Allow-Methods $cors_methods always;
    add_header Access-Control-Allow-Headers $cors_headers always;
    add_header Access-Control-Allow-Credentials $cors_credentials always;

    location / {
        if ($request_method = OPTIONS) {
            return 204;
        }
        proxy_pass http://backend;
    }
}

Dieser Ansatz sendet CORS-Header nur für zulässige Ursprünge und verhindert so die Offenlegung von Informationen gegenüber nicht autorisierten Ursprüngen.

Implementierung von A/B-Tests

Implementieren Sie serverseitige A/B-Tests:

# Use split_clients for random assignment
split_clients "${remote_addr}${request_uri}" $ab_random {
    50%     "A";
    *       "B";
}

# Override with cookie if user already assigned
map $cookie_ab_variant $ab_variant {
    default     $ab_random;
    "A"         "A";
    "B"         "B";
}

# Select backend based on variant
map $ab_variant $ab_backend {
    default     "control_backend";
    "A"         "control_backend";
    "B"         "experiment_backend";
}

server {
    listen 80;
    server_name example.com;

    location / {
        add_header Set-Cookie "ab_variant=$ab_variant; Path=/; Max-Age=86400";
        proxy_pass http://$ab_backend;
        proxy_set_header X-AB-Variant $ab_variant;
    }
}

Content Security Policy pro Route

Wenden Sie unterschiedliche Sicherheitsrichtlinien auf verschiedene Teile Ihrer Anwendung an:

map $uri $csp_policy {
    default         "default-src 'self'; script-src 'self'";
    "~^/admin/"     "default-src 'self'; script-src 'self' 'unsafe-inline'";
    "~^/embed/"     "frame-ancestors *";
    "~^/api/"       "default-src 'none'";
}

server {
    listen 443 ssl;
    server_name example.com;

    add_header Content-Security-Policy $csp_policy always;

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

Kaskadierendes Map-Muster

Sie können mehrere Maps für komplexe bedingte Logik miteinander verketten:

# First map: determine request category
map $uri $request_category {
    default         "page";
    "~^/api/"       "api";
    "~^/static/"    "static";
    "~^/admin/"     "admin";
}

# Second map: determine cache duration based on category
map $request_category $cache_duration {
    default     "1h";
    api         "0";
    static      "30d";
    admin       "0";
}

# Third map: determine log format based on category
map $request_category $log_format_name {
    default     "main";
    api         "api_detailed";
    static      "minimal";
    admin       "admin_audit";
}

Dieses kaskadierende Muster hält jede Map auf eine einzelne Entscheidung fokussiert und verbessert die Wartbarkeit.

Häufige Fehler und wie Sie sie vermeiden

Fehler 1: map im Server-Kontext platzieren

Maps müssen sich im http-Kontext befinden:

# WRONG - will cause configuration error
server {
    map $host $backend {
        example.com backend1;
    }
}

# CORRECT
http {
    map $host $backend {
        default     backend1;
        example.com backend2;
    }

    server {
        # Use $backend here
    }
}

Fehler 2: Den Standardwert vergessen

Fügen Sie immer einen Standardwert hinzu, um leere Variablen zu verhindern:

# RISKY - no default
map $http_x_custom_header $allowed {
    "secret-token"  1;
}

# SAFE - explicit default
map $http_x_custom_header $allowed {
    default         0;
    "secret-token"  1;
}

Fehler 3: Falsches Escaping von regulären Ausdrücken

Denken Sie daran, dass Map-Werte nicht automatisch in Anführungszeichen gesetzt werden:

# WRONG - dot matches any character
map $host $backend {
    api.example.com     "api_backend";
}

# CORRECT for literal matching (no regex needed for exact match)
map $host $backend {
    default             "default_backend";
    api.example.com     "api_backend";
}

# CORRECT for regex with literal dot
map $host $backend {
    default                 "default_backend";
    "~^api[.]example[.]com$" "api_backend";
}

Fehler 4: Reguläre Ausdrücke verwenden, wenn sie nicht nötig sind

Exakte Übereinstimmungen sind schneller als reguläre Ausdrücke:

# SLOWER - unnecessary regex
map $request_method $is_post {
    default     0;
    "~^POST$"   1;
}

# FASTER - exact match
map $request_method $is_post {
    default     0;
    POST        1;
}

Debuggen von map-Variablen

Um die Werte von Map-Variablen zu debuggen, fügen Sie sie Ihrem Log-Format oder Ihren Antwort-Headern hinzu:

log_format debug_maps '$remote_addr - $request_uri - '
                      'mobile=$is_mobile backend=$backend_pool';

server {
    access_log /var/log/nginx/debug.log debug_maps;

    location / {
        add_header X-Debug-Mobile $is_mobile;
        add_header X-Debug-Backend $backend_pool;
        # ...
    }
}

Sie können auch curl verwenden, um Ihre Maps zu testen:

# Test mobile detection
curl -H "User-Agent: Mozilla/5.0 (iPhone)" http://localhost/ -I

# Test hostname routing
curl -H "Host: staging.example.com" http://localhost/ -I

Sicherheitsüberlegungen

Validieren Sie map-Konfigurationen mit Gixy

Gixy ist ein NGINX-Konfigurationsanalysator, der auf häufige Sicherheitsprobleme prüft, einschließlich Maps ohne Standardwerte. Führen Sie ihn als Teil Ihrer Deployment-Pipeline aus:

gixy /etc/nginx/nginx.conf

Gixy warnt Sie vor:
– Maps ohne Standardwerte
– potenziell gefährlichen regulären Ausdrücken
– Variablen, die gefährliche Zeichen enthalten könnten

Vermeiden Sie Benutzereingaben in sensiblen Kontexten

Seien Sie vorsichtig, wenn Map-Ergebnisse in sicherheitskritischen Kontexten verwendet werden:

# POTENTIALLY DANGEROUS if $uri contains user input
map $uri $allowed_origin {
    "/api/public"   "*";
    default         "";
}

add_header Access-Control-Allow-Origin $allowed_origin;

Validieren Sie stets, dass Ihre Map-Muster nicht durch manipulierte Eingaben ausgenutzt werden können.

Leistungsbenchmarks

Um die Leistung von Maps zu verstehen, beachten Sie Folgendes:

  • Nachschlagevorgänge bei exakter Übereinstimmung: O(1)-Hash-Tabellen-Nachschlagevorgang, typischerweise unter 100 Nanosekunden
  • Wildcard-Nachschlagevorgänge: O(1) mit optimierten Hash-Tabellen für DNS-Muster
  • Regex-Nachschlagevorgänge: O(n), wobei n die Anzahl der Regex-Muster ist, die sequenziell ausgewertet werden

Bei einer Map mit 1000 exakten Einträgen ist die Nachschlagezeit im Wesentlichen dieselbe wie bei einer Map mit 10 Einträgen. 1000 Regex-Muster sind jedoch deutlich langsamer als 10.

Fazit

Die NGINX map-Direktive ist ein unverzichtbares Werkzeug für jeden ernsthaften NGINX-Administrator. Sie bietet eine saubere, leistungsfähige und wartbare Möglichkeit, bedingte Logik in Ihrer NGINX-Konfiguration umzusetzen. Wenn Sie Maps beherrschen, können Sie:

  • unübersichtliche Ketten von if-Anweisungen beseitigen
  • ausgefeiltes Routing und Rate Limiting implementieren
  • Dynamische Sicherheitsrichtlinien erstellen
  • Infrastruktur für A/B-Tests aufbauen
  • URL-Weiterleitungen effizient verwalten

Denken Sie daran, immer Standardwerte anzugeben, wenn möglich exakte Übereinstimmungen zu verwenden und Ihre Konfigurationen mit Tools wie Gixy zu validieren. Mit diesen Praktiken wird die map-Direktive zu einem der wertvollsten Werkzeuge in Ihrem NGINX-Toolkit.
Von der einmaligen Validierung zur kontinuierlichen Abdeckung. map-Direktiven sind dicht und leicht falsch anzuwenden. Kontinuierliches Scannen erkennt den nächsten Fehler. GetPageSpeed Amplify führt geplante gixy-Scans auf jedem Host aus und verknüpft die Ergebnisse mit Live-Laufzeitmetriken von NGINX. Drop-in-kompatibel mit dem veralteten nginx-amplify-agent (EOL Januar 2026).