Skip to main content

Directiva map de NGINX: Guía de variables condicionales

Este artículo es una traducción del original en inglés.


La directiva map de NGINX es una de las características más potentes y, a la vez, menos utilizadas en la configuración de NGINX. Le permite crear variables cuyos valores dependen de los valores de otras variables, lo que habilita una lógica condicional compleja sin la penalización de rendimiento de múltiples sentencias if. Esta guía cubre todo lo que necesita saber sobre la directiva map de NGINX, desde la sintaxis básica hasta aplicaciones avanzadas del mundo real.

¿Qué es la directiva map de NGINX?

La directiva map crea una nueva variable cuyo valor se determina al mapear el valor de una variable de origen contra un conjunto de patrones. Piense en ella como una sentencia switch o una tabla de búsqueda altamente optimizada que se ejecuta con un costo casi nulo durante el procesamiento de la solicitud.

La sintaxis básica es:

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

El bloque map debe colocarse en el contexto http, fuera de cualquier bloque server. Esto se debe a que NGINX compila el map en una tabla hash eficiente durante la carga de la configuración, no durante el procesamiento de la solicitud.

¿Por qué usar la directiva map en lugar de sentencias if?

Muchos administradores de NGINX recurren a las sentencias if cuando necesitan lógica condicional. Sin embargo, el principio de que if is evil en NGINX existe por una buena razón. La directiva map ofrece varias ventajas:

Rendimiento: Los maps se compilan en tablas hash en el momento de la carga de la configuración. Las búsquedas son O(1) para coincidencias exactas, lo que las hace extremadamente rápidas independientemente de cuántas entradas tenga.

Configuración más limpia: En lugar de bloques if anidados dispersos por toda su configuración, los maps centralizan la lógica condicional en un solo lugar.

Reutilización: Una variable definida por un map se puede usar en cualquier parte de su configuración: en bloques server, bloques location, formatos de registro y más.

Seguridad: A diferencia de las sentencias if, los maps no pueden causar comportamientos inesperados con otras directivas. Para obtener más información sobre la configuración de encabezados en NGINX, consulte nuestra guía sobre los inconvenientes de add_header en NGINX.

Ejemplos básicos de la directiva map

Detección de dispositivos móviles

Uno de los usos más comunes de la directiva map es la detección de dispositivos basada en el User-Agent:

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

El prefijo ~* indica una coincidencia de expresión regular sin distinción entre mayúsculas y minúsculas. Luego puede usar $is_mobile en cualquier parte de su configuración:

server {
    listen 80;
    server_name example.com;

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

Configuración de servidores backend según el nombre de host

Puede usar maps para enrutar solicitudes a diferentes servidores backend según el nombre de host entrante:

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;
    }
}

Comprender la coincidencia de patrones de map

La directiva map de NGINX admite varios métodos de coincidencia de patrones, evaluados en un orden específico:

1. Coincidencias exactas de cadenas

La forma más simple coincide exactamente con la variable de origen:

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

2. Patrones de expresiones regulares

Prefije un patrón con ~ para una regex sensible a mayúsculas y minúsculas o ~* para una insensible:

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

Las expresiones regulares pueden incluir grupos de captura. Los valores capturados están disponibles como $1, $2, etc., dentro del valor del map:

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

Para obtener más detalles sobre los patrones de NGINX, consulte nuestro artículo sobre prioridad de location en NGINX.

3. Patrones de nombres de host comodín

Cuando se especifica el parámetro hostnames, NGINX habilita una coincidencia comodín especial optimizada para nombres de dominio:

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

El parámetro hostnames habilita dos tipos de comodín:

  • *.example.com – coincide con cualquier subdominio (api.example.com, www.example.com)
  • .example.com – igual que el anterior, notación abreviada
  • mail.* – coincide con mail.example.com, mail.example.org, etc.

NGINX almacena estos comodines en tablas hash optimizadas, lo que hace que las búsquedas sean eficientes incluso con miles de entradas.

Prioridad de coincidencia de patrones

Cuando varios patrones podrían coincidir, NGINX los evalúa en este orden:

  1. Coincidencia exacta de cadena (prioridad más alta)
  2. Comodín de prefijo (*.example.com)
  3. Comodín de sufijo (www.*)
  4. Expresiones regulares (en orden de aparición)
  5. Valor predeterminado (prioridad más baja)

Gana la primera coincidencia. Para las expresiones regulares, el orden importa: los patrones anteriores tienen precedencia.

El parámetro default

Todo map debe incluir un valor default. Este valor se usa cuando ningún patrón coincide:

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

Advertencia de seguridad: Omitir el default puede provocar valores de variable vacíos, lo que podría eludir los controles de seguridad. Herramientas de seguridad como Gixy verifican específicamente los maps sin valores predeterminados y los marcan como problemas de gravedad media.

El parámetro volatile

De forma predeterminada, NGINX almacena en caché los resultados del map por solicitud. El parámetro volatile desactiva este almacenamiento en caché:

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

Use volatile cuando:
– La variable de origen cambia durante el procesamiento de la solicitud
– Necesita una evaluación nueva cada vez que se accede a la variable
– El resultado del map depende de variables que otros módulos pueden modificar

En la mayoría de los casos, no debe usar volatile, ya que el comportamiento de almacenamiento en caché predeterminado mejora el rendimiento.

La directiva include dentro de los maps

Para maps grandes, puede dividir las entradas en archivos separados:

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

El archivo incluido contiene entradas de map simples:

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

Este enfoque es excelente para mantener grandes listas de bloqueo o listas blancas sin saturar su configuración principal.

Ajuste de las tablas hash de map

Para la mayoría de las configuraciones, los valores predeterminados de NGINX funcionan perfectamente. Solo necesita ajustar la configuración de hash cuando NGINX emite advertencias o errores sobre las tablas hash de map.

Dos directivas controlan las tablas hash de map:

  • map_hash_max_size – Número máximo de buckets (predeterminado: 2048)
  • map_hash_bucket_size – Tamaño de cada bucket (predeterminado: línea de caché de la CPU, normalmente 64)

Importante: Si necesita valores no predeterminados, estas directivas deben aparecer antes de cualquier bloque map en su configuración. Colocarlas después de un bloque map provoca errores.

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

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

Cómo interpretar las advertencias: Si NGINX indica “could not build optimal map_hash”, tiene muchas entradas. Aumente map_hash_max_size.

Cómo interpretar los errores: Si NGINX indica “increase map_hash_bucket_size”, tiene claves muy largas (más de 46 caracteres). Aumente map_hash_bucket_size a 128.

Para obtener una explicación detallada del algoritmo hash, los límites de longitud de clave, los umbrales probados y el flujo de trabajo completo de ajuste, consulte nuestra guía completa: Ajuste del hash de map de NGINX.

Casos de uso reales de la directiva map

Limitación de velocidad con maps

Cree reglas de limitación de velocidad sofisticadas usando maps:

# 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;
    }
}

Esta configuración:
– Aplica una limitación de velocidad diferente a distintos patrones de URL
– Exime por completo a las IP de la lista blanca
– Omite la limitación de velocidad para archivos estáticos
– Usa un patrón de maps en cascada para una lógica compleja

Redirecciones de URL con maps

Gestione las redirecciones de URL heredadas de forma eficiente:

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;
    }
}

Este patrón gestiona cientos de redirecciones con una configuración mínima y un rendimiento óptimo.

Configuración dinámica de CORS

Implemente CORS seguro usando 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;
    }
}

Este enfoque solo envía encabezados CORS para orígenes permitidos, lo que evita la divulgación de información a orígenes no autorizados.

Implementación de pruebas A/B

Implemente pruebas A/B del lado del servidor:

# 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;
    }
}

Política de seguridad de contenido por ruta

Aplique políticas de seguridad diferentes a distintas partes de su aplicación:

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;
    }
}

Patrón de maps en cascada

Puede encadenar varios maps para una lógica condicional compleja:

# 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";
}

Este patrón en cascada mantiene cada map enfocado en una sola decisión, lo que mejora el mantenimiento.

Errores comunes y cómo evitarlos

Error 1: Colocar map en el contexto server

Los maps deben estar en el contexto http:

# 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
    }
}

Error 2: Olvidar el default

Incluya siempre un default para evitar variables vacías:

# 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;
}

Error 3: Escapado incorrecto de regex

Recuerde que los valores del map no se entrecomillan automáticamente:

# 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";
}

Error 4: Usar expresiones regulares cuando no son necesarias

Las coincidencias exactas son más rápidas que las regex:

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

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

Depuración de variables de map

Para depurar los valores de las variables de map, agréguelos a su formato de registro o a los encabezados de respuesta:

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;
        # ...
    }
}

También puede usar curl para probar sus maps:

# 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

Consideraciones de seguridad

Valide las configuraciones de map con Gixy

Gixy es un analizador de configuración de NGINX que verifica problemas de seguridad comunes, incluidos los maps sin valores predeterminados. Ejecútelo como parte de su canal de implementación:

gixy /etc/nginx/nginx.conf

Gixy le advertirá sobre:
– Maps sin valores predeterminados
– Expresiones regulares potencialmente peligrosas
– Variables que podrían contener caracteres peligrosos

Evite la entrada del usuario en contextos sensibles

Tenga cuidado cuando los resultados del map se usan en contextos sensibles para la seguridad:

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

add_header Access-Control-Allow-Origin $allowed_origin;

Valide siempre que sus patrones de map no puedan explotarse mediante entradas manipuladas.

Evaluaciones comparativas de rendimiento

Para comprender el rendimiento de map, tenga en cuenta que:

  • Búsquedas de coincidencia exacta: búsqueda en tabla hash O(1), normalmente por debajo de 100 nanosegundos
  • Búsquedas con comodín: O(1) con tablas hash optimizadas para patrones DNS
  • Búsquedas de regex: O(n), donde n es el número de patrones de regex, evaluados secuencialmente

Para un map con 1000 entradas exactas, el tiempo de búsqueda es esencialmente el mismo que el de un map con 10 entradas. Sin embargo, 1000 patrones de regex serán significativamente más lentos que 10.

Conclusión

La directiva map de NGINX es una herramienta esencial para cualquier administrador de NGINX serio. Proporciona una forma limpia, eficiente y mantenible de implementar lógica condicional en su configuración de NGINX. Al dominar los maps, puede:

  • Eliminar las cadenas desordenadas de sentencias if
  • Implementar enrutamiento y limitación de velocidad sofisticados
  • Crear políticas de seguridad dinámicas
  • Construir infraestructura de pruebas A/B
  • Gestionar redirecciones de URL de forma eficiente

Recuerde incluir siempre valores predeterminados, usar coincidencias exactas cuando sea posible y validar sus configuraciones con herramientas como Gixy. Con estas prácticas implementadas, la directiva map se convierte en una de las herramientas más valiosas de su conjunto de herramientas de NGINX.
De la validación puntual a la cobertura continua. Las directivas map son densas y fáciles de usar mal. El escaneo continuo detecta el siguiente error. GetPageSpeed Amplify ejecuta escaneos programados de gixy en cada host y vincula los hallazgos con métricas de tiempo de ejecución de NGINX en vivo. Compatible de forma directa con el obsoleto nginx-amplify-agent (fin de vida en enero de 2026).