Reglas de coincidencia de ubicación de Nginx explicadas con ejemplos reales

Probablemente hayas ajustado una configuración de Nginx, recargado y te hayas preguntado por qué tu bloque location simplemente no parece aplicarse. Quizás una solicitud de archivo estático esté llegando a tu manejador PHP, o una ruta de API esté siendo absorbida por un catch-all. El culpable suele ser el algoritmo de coincidencia de ubicación de Nginx: no es tan sencillo como parece.

En esta guía, desglosaremos cómo Nginx selecciona un bloque location, con ejemplos reales que puedes probar. Al final, sabrás exactamente qué bloque gana y por qué.

Cómo funciona la coincidencia de ubicación de Nginx

Cuando llega una solicitud, Nginx compara el URI con todos los bloques location definidos. El proceso de coincidencia sigue un orden específico:

1. Coincidencia exacta (=) — máxima prioridad. Si se encuentra, Nginx se detiene y la usa.
2. Coincidencia de prefijo más larga — Nginx recuerda la ubicación de prefijo que coincide más larga.
3. Coincidencia de expresión regular (~ o ~*) — se verifica en orden de aparición. La primera regex que coincide gana, anulando la coincidencia de prefijo (a menos que se use ^~).
4. Coincidencia de prefijo con ^~ — si el prefijo coincidente más largo tiene ^~, Nginx omite la verificación de regex y lo usa.
5. Si ninguna regex coincide, se usa la coincidencia de prefijo más larga.

Ese es el algoritmo central. Veámoslo en acción.

Modificadores de ubicación: referencia rápida

Ejemplo real 1: Archivos estáticos vs. PHP

Considera esta configuración común:

server {
    listen 80;
    server_name example.com;

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

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    }
}

Una solicitud para /index.php coincide con la regex \.php$, por lo que va a PHP-FPM. Una solicitud para /logo.png no coincide con la regex, por lo que recurre al prefijo / y sirve el archivo estático. Sencillo, ¿verdad?

Pero, ¿y si quieres servir /uploads/photo.php como un archivo estático (quizás en realidad sea una imagen)? Puedes agregar una coincidencia exacta:

location = /uploads/photo.php {
    root /var/www/html;
}

Ahora esa coincidencia exacta tiene prioridad sobre la regex.

Ejemplo real 2: Enrutamiento de API con prefijo y regex

Supongamos que tienes una API bajo /api/ y quieres redirigir todas las solicitudes a un backend, excepto una verificación de estado que devuelve una respuesta estática.

location = /api/health {
    return 200 "OK";
}

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

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

Sigamos /api/health: la coincidencia exacta gana, devuelve 200. Para /api/users: no hay exacta, no hay regex (no coincide con special), por lo que se usa el prefijo más largo /api/. Para /api/v1/special: la regex coincide, por lo que anula el prefijo y va a special-backend.

Esto demuestra cómo una regex puede anular una coincidencia de prefijo. Si quisieras que el prefijo siempre ganara, usarías ^~ en su lugar.

Ejemplo real 3: El poder de ^~

Imagina que tienes un directorio /static/ con archivos que nunca deberían ser procesados por PHP, incluso si terminan en .php. Usar ^~ asegura que Nginx no verifique las ubicaciones regex.

location ^~ /static/ {
    root /var/www/html;
}

location ~ \.php$ {
    fastcgi_pass unix:/run/php/php8.2-fpm.sock;
}

Una solicitud para /static/script.php coincide con el prefijo ^~ /static/. Debido a ^~, Nginx omite la verificación de regex y sirve el archivo directamente. Sin ^~, la regex coincidiría y PHP-FPM lo ejecutaría, un riesgo de seguridad potencial.

Errores comunes y cómo evitarlos

• El orden de las regex importa: Nginx verifica las ubicaciones regex en el orden en que aparecen en la configuración. Coloca los patrones más específicos primero.
• Falta de barras finales: location /api y location /api/ son diferentes. El primero coincide con /api y /apix, mientras que el segundo coincide con /api/ y /api/users. Sé preciso.
• Prefijos superpuestos: El prefijo más largo gana, por lo que location /api/v1 tiene prioridad sobre location /api para /api/v1/users.
• Olvidar ^~ para activos estáticos: Úsalo para evitar que las regex secuestren solicitudes de archivos estáticos.
• Sensibilidad a mayúsculas: ~ distingue mayúsculas de minúsculas, ~* no. Usa ~* para extensiones de archivo.

Depuración de la coincidencia de ubicación

Si no estás seguro de qué ubicación se está utilizando, habilita el registro de depuración en Nginx. Agrega error_log /var/log/nginx/error.log debug; en tu bloque server, recarga y revisa el log. Verás líneas como test location: "/api/users" y using configuration "/api/".

Alternativamente, usa return 200 "matched: /api/"; temporalmente en cada ubicación para ver cuál responde.

Preguntas frecuentes

¿Cuál es el orden de prioridad de los modificadores de ubicación de Nginx?

La coincidencia exacta (=) es la más alta, luego el prefijo más largo con ^~, luego la regex (~ o ~*) en orden, luego la coincidencia de prefijo más larga sin ^~.

¿Puede una ubicación regex anular una ubicación de prefijo?

Sí, a menos que la ubicación de prefijo use ^~. Las ubicaciones regex se verifican después de la coincidencia de prefijo más larga, y si una regex coincide, tiene prioridad sobre un prefijo regular.

¿Cómo hago coincidir una ubicación solo para un archivo específico?

Usa una coincidencia exacta con =, por ejemplo, location = /favicon.ico. Esto asegura que solo ese URI exacto coincida.

Domina tu configuración de Nginx

Comprender la coincidencia de ubicación es clave para una configuración de Nginx confiable. Prueba tus configuraciones con nginx -t y usa registros de depuración cuando tengas dudas. Si estás lidiando con registros de Nginx y necesitas analizar patrones de tráfico, prueba nuestro Analizador de registros de Nginx para analizar y visualizar tus registros rápidamente.