Regras de Correspondência de Location no Nginx com Exemplos

Você provavelmente já ajustou uma configuração do Nginx, recarregou e se perguntou por que seu bloco location simplesmente não parece ser aplicado. Talvez uma requisição de arquivo estático esteja caindo no seu handler PHP, ou uma rota de API esteja sendo engolida por um catch-all. O culpado geralmente é o algoritmo de correspondência de location do Nginx — ele não é tão direto quanto parece.

Neste guia, vamos detalhar como o Nginx seleciona um bloco location, com exemplos reais que você pode testar. Ao final, você saberá exatamente qual bloco vence e por quê.

Como Funciona a Correspondência de Location no Nginx

Quando uma requisição chega, o Nginx compara a URI com todos os blocos location definidos. O processo de correspondência segue uma ordem específica:

1. Correspondência exata (=) — prioridade máxima. Se encontrada, o Nginx para e a utiliza.
2. Correspondência de prefixo mais longa — o Nginx memoriza o location de prefixo que corresponde mais longamente.
3. Correspondência por expressão regular (~ ou ~*) — verificada na ordem de aparição. A primeira regex que corresponder vence, sobrepondo a correspondência de prefixo (a menos que ^~ seja usado).
4. Correspondência de prefixo com ^~ — se o prefixo mais longo correspondente tiver ^~, o Nginx pula a verificação de regex e o utiliza.
5. Se nenhuma regex corresponder, a correspondência de prefixo mais longa é usada.

Esse é o algoritmo central. Vamos vê-lo em ação.

Modificadores de Location: Referência Rápida

Exemplo Real 1: Arquivos Estáticos vs. PHP

Considere esta configuração comum:

server {
    listen 80;
    server_name example.com;

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

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

Uma requisição para /index.php corresponde à regex \.php$, então vai para o PHP-FPM. Uma requisição para /logo.png não corresponde à regex, então cai no prefixo / e serve o arquivo estático. Simples, certo?

Mas e se você quiser servir /uploads/photo.php como arquivo estático (talvez seja na verdade uma imagem)? Você pode adicionar uma correspondência exata:

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

Agora essa correspondência exata tem precedência sobre a regex.

Exemplo Real 2: Roteamento de API com Prefixo e Regex

Suponha que você tenha uma API em /api/ e queira fazer proxy de todas as requisições para um backend, exceto por um health check que retorna uma resposta 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;
}

Vamos traçar /api/health: a correspondência exata vence, retorna 200. Para /api/users: sem exata, sem regex (não corresponde a special), então o prefixo mais longo /api/ é usado. Para /api/v1/special: a regex corresponde, então sobrepõe o prefixo e vai para special-backend.

Isso demonstra como a regex pode sobrepor uma correspondência de prefixo. Se você quisesse que o prefixo sempre vencesse, usaria ^~ em vez disso.

Exemplo Real 3: O Poder do ^~

Imagine que você tenha um diretório /static/ com arquivos que nunca devem ser processados pelo PHP, mesmo que terminem com .php. Usar ^~ garante que o Nginx não verifique locations de regex.

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

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

Uma requisição para /static/script.php corresponde ao prefixo ^~ /static/. Por causa do ^~, o Nginx pula a verificação de regex e serve o arquivo diretamente. Sem o ^~, a regex corresponderia e o PHP-FPM o executaria — um potencial risco de segurança.

Armadilhas Comuns e Como Evitá-las

• A ordem das regex importa: o Nginx verifica locations de regex na ordem em que aparecem na configuração. Coloque padrões mais específicos primeiro.
• Barras finais ausentes: location /api e location /api/ são diferentes. O primeiro corresponde a /api e /apix, enquanto o segundo corresponde a /api/ e /api/users. Seja preciso.
• Prefixos sobrepostos: o prefixo mais longo vence, então location /api/v1 tem precedência sobre location /api para /api/v1/users.
• Esquecer ^~ para assets estáticos: use-o para impedir que a regex sequestre requisições de arquivos estáticos.
• Case sensitivity: ~ é case-sensitive, ~* não é. Use ~* para extensões de arquivo.

Depurando a Correspondência de Location

Se você não tem certeza de qual location está sendo usado, habilite o log de debug no Nginx. Adicione error_log /var/log/nginx/error.log debug; no seu bloco server, recarregue e verifique o log. Você verá linhas como test location: "/api/users" e using configuration "/api/".

Alternativamente, use return 200 "matched: /api/"; temporariamente em cada location para ver qual responde.

FAQ

Qual é a ordem de prioridade dos modificadores de location do Nginx?

A correspondência exata (=) é a mais alta, depois o prefixo mais longo com ^~, depois regex (~ ou ~*) em ordem, depois a correspondência de prefixo mais longa sem ^~.

Uma location de regex pode sobrepor uma location de prefixo?

Sim, a menos que a location de prefixo use ^~. Locations de regex são verificadas após a correspondência de prefixo mais longa, e se uma regex corresponder, ela tem precedência sobre um prefixo comum.

Como faço para corresponder uma location apenas para um arquivo específico?

Use uma correspondência exata com =, por exemplo, location = /favicon.ico. Isso garante que apenas aquela URI exata seja correspondida.

Domine Sua Configuração do Nginx

Entender a correspondência de location é fundamental para uma configuração confiável do Nginx. Teste suas configurações com nginx -t e use logs de debug em caso de dúvida. Se você está lidando com logs do Nginx e precisa analisar padrões de tráfego, experimente nosso Analisador de Logs do Nginx para processar e visualizar seus logs rapidamente.