Blocos de Localização Nginx Explicados: Roteamento de Tráfego Web

Os blocos de localização Nginx decidem o que acontece depois que uma requisição chega ao bloco server correto. Eles são a razão pela qual /static/app.css pode ser servido do disco, /api/users pode ser proxy para uma aplicação e /.git/config pode ser negado antes de vazar algo sensível.

A maioria dos erros com blocos de localização não são erros de sintaxe. São erros de prioridade. Uma regex captura uma requisição que você esperava que um bloco de prefixo tratasse. Um caminho root anexa mais URI do que você pensava. Um proxy_pass com uma barra no final reescreve a URI upstream de forma diferente da mesma diretiva sem ela. Os exemplos abaixo focam nesses pontos reais de falha.

O Papel e a Anatomia de um Bloco de Localização

Um bloco location define como o Nginx deve responder a requisições com base na URI (Uniform Resource Identifier) da requisição. Esses blocos estão sempre aninhados dentro de um bloco server.

Quando um cliente faz uma requisição (ex.: GET /images/logo.png), o Nginx verifica a URI da requisição em todos os blocos de localização definidos dentro do bloco server que está ouvindo para determinar o tratamento apropriado, como servir um arquivo, redirecionar o cliente ou fazer proxy da requisição para um servidor de aplicação.

Sintaxe Básica

A sintaxe requer um modificador (ou a falta dele) seguido por um padrão (URI):

location [modificador] [padrão] {
    # Diretivas de configuração (ex.: root, index, proxy_pass)
}

Entendendo os Tipos de Correspondência de Localização (Os Modificadores)

O Nginx oferece um pequeno conjunto de estilos de correspondência de localização. A escolha afeta tanto a precisão do roteamento quanto quanto trabalho o Nginx faz antes de escolher um manipulador.

1. Correspondência de Prefixo (Sem Modificador)

Este é o tipo de correspondência padrão. O Nginx procura pela string inicial mais longa que corresponde à URI da requisição.

Modificador	Exemplo	Comportamento	Melhor Caso de Uso
(nenhum)	location /blog/	Corresponde a URIs começando com /blog/ (ex.: /blog/post/1).	Propósito geral, definindo grandes seções de um site.

Exemplo:

location /docs/ {
    root /var/www/html/public;
    # Se a URI for /docs/manual.pdf, o Nginx procura por /var/www/html/public/docs/manual.pdf
}

2. Correspondência Exata (=)

Este modificador força uma correspondência exata entre a URI e o padrão. Se corresponder, o Nginx para imediatamente de procurar por outras localizações. Este é o tipo de correspondência mais rápido.

Modificador	Exemplo	Comportamento	Melhor Caso de Uso
=	location = /favicon.ico	Corresponde apenas exatamente à URI /favicon.ico.	Manipular arquivos específicos e frequentemente solicitados ou páginas padrão.

3. Prefixo Mais Longo, Não-Regex (^~)

Esta é uma correspondência de prefixo especializada. Se o Nginx encontrar a correspondência de prefixo mais longa usando ^~, ele para imediatamente de verificar qualquer bloco de localização de expressão regular (regex), efetivamente os sobrescrevendo.

Modificador	Exemplo	Comportamento	Melhor Caso de Uso
^~	location ^~ /assets/	Corresponde a URIs começando com /assets/ e impede que correspondências regex mais lentas sejam verificadas.	Servir ativos estáticos rapidamente e garantir que diretórios de ativos sejam manipulados de forma previsível.

4. Expressão Regular Sensível a Maiúsculas/Minúsculas (~)

Isso usa Expressões Regulares Compatíveis com Perl (PCRE) para correspondência. É poderoso, mas mais lento que correspondências de prefixo. O primeiro bloco regex correspondente vence.

Modificador	Exemplo	Comportamento	Melhor Caso de Uso
~	location ~ \.php$	Corresponde a qualquer URI terminando em .php.	Processamento de tipo de arquivo específico (ex.: passar scripts PHP para PHP-FPM).

5. Expressão Regular Insensível a Maiúsculas/Minúsculas (~*)

Idêntico a ~, mas a correspondência ignora maiúsculas/minúsculas da URI.

Modificador	Exemplo	Comportamento	Melhor Caso de Uso
~*	`location ~* .(jpg	gif	png)$`

---

A Ordem Crítica de Processamento de Localização

Entender a ordem na qual o Nginx processa os blocos de localização é vital para evitar comportamentos inesperados. O Nginx não simplesmente lê os arquivos de configuração de cima para baixo. Ele usa uma hierarquia estrita:

1. Correspondência Exata (=): O Nginx primeiro verifica todos os blocos de correspondência exata. Se uma correspondência for encontrada, o processamento para imediatamente e a requisição é tratada por aquele bloco.
2. Candidato de Prefixo Mais Longo: O Nginx encontra a localização de prefixo correspondente mais longa, incluindo localizações de prefixo simples e localizações ^~.
3. Pular Regex para ^~: Se a melhor correspondência de prefixo usar ^~, o Nginx a usa e pula as verificações de regex.
4. Expressões Regulares (~ e ~*): Se o melhor prefixo não foi ^~, o Nginx verifica as localizações regex na ordem em que aparecem no arquivo de configuração. O primeiro bloco regex correspondente vence.
5. Correspondência de Prefixo Padrão Mais Longa: Se nenhuma correspondência regex vencer, o Nginx usa o candidato de prefixo mais longo que já encontrou. Em muitas configurações, location / é o fallback final.

É por isso que ^~ /static/ é comum. Sem ^~, uma regex posterior como location ~* \.(css|js)$ ainda pode vencer para /static/app.css. Às vezes isso é aceitável. Às vezes, ignora os cabeçalhos de cache, o caminho raiz ou as regras de acesso que você esperava para todo o diretório /static/.

Cenários Práticos de Configuração

1. Priorizando Ativos Estáticos para Desempenho

Para garantir que o Nginx sirva arquivos estáticos diretamente e rapidamente, prevenindo verificações regex mais lentas e processamento desnecessário pelo servidor de aplicação, use o modificador ^~.

server {
    listen 80;
    server_name myapp.com;

    # 1. Correspondência exata para a página principal (maior prioridade)
    location = / {
        proxy_pass http://backend_app_server;
    }

    # 2. Manipulação rápida para ativos estáticos, ignorando verificações regex
    location ^~ /static/ {
        root /var/www/site;
        expires 30d;
    }

    # 3. Expressão regular para arquivos de mídia comuns
    location ~* \.(gif|ico|css|js)$ {
        root /var/www/site;
        expires 7d;
    }

    # 4. Fallback para todas as outras requisições dinâmicas
    location / {
        proxy_pass http://backend_app_server;
    }
}

2. Roteamento e Proxy de Tráfego de API

Ao usar o Nginx como um proxy reverso, os blocos de localização direcionam o tráfego para o servidor de aplicação upstream correto.

location /api/v1/ {
    # Garantir que o Nginx respeite as configurações de conexão do cliente
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;

    # Roteia todo o tráfego começando com /api/v1/ para o serviço backend
    proxy_pass http://api_backend_service/v1/;

    # Com uma URI no proxy_pass, o Nginx substitui o prefixo correspondente.
    # /api/v1/users torna-se /v1/users upstream.
}

Esse comportamento da barra no final vale a pena testar. Esses dois exemplos são diferentes:

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

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

A primeira forma passa a URI original, incluindo /api/..., para o upstream. A segunda forma substitui o prefixo /api/ correspondido por /. Se seu upstream de repente começar a retornar 404s após uma pequena edição de configuração, verifique isso antes de culpar o aplicativo.

3. Protegendo Diretórios Sensíveis

Blocos de localização podem ser usados para negar acesso externo a diretórios internos sensíveis, como arquivos de configuração ou diretórios ocultos como .git.

# Negar acesso a arquivos começando com um ponto (arquivos ocultos)
location ~ /\.(ht|svn|git) {
    deny all;
    return 404; # Retornar 404 em vez de 403 para evitar revelar sua existência
}

# Negar acesso a diretórios de configuração específicos
location /app/config/ {
    deny all;
}

Para arquivos ocultos, muitas equipes usam uma regra de negação mais ampla:

location ~ /\.(?!well-known/) {
    deny all;
    return 404;
}

A exceção mantém /.well-known/ disponível para coisas como desafios de certificado ACME HTTP-01, enquanto ainda bloqueia a maioria dos dotfiles. Teste isso cuidadosamente se seu site serve outros caminhos legítimos prefixados com ponto.

Aviso de Segurança: Usando alias vs. root

Ao configurar caminhos de arquivo dentro de um bloco de localização, esteja atento à diferença entre root e alias.

• root: Anexa a URI completa da requisição ao caminho definido. (ex.: location /images/ + root /data/ leva a /data/images/filename.jpg)
• alias: Substitui a parte correspondida da URI pelo caminho definido. Isso é frequentemente necessário quando o bloco de localização usa uma regex ou precisa remover parte do caminho antes de servir o arquivo. (ex.: location /static/ + alias /opt/app/files/ leva a /opt/app/files/filename.jpg)

4. Manipulando Barras no Final e Redirecionamentos

Muitas vezes é desejável impor uma estrutura de URL consistente, como garantir que diretórios sempre terminem com uma barra no final (/).

# Forçar uma barra no final para caminhos de diretório se estiver faltando
location ~* /[a-z0-9\-_]+$ {
    # Se a URI corresponder a um arquivo, o Nginx tentará servi-lo. Se não, tratar como um diretório.
    # Verificar se a URI solicitada mapeia para um diretório no disco:
    if (-d $request_filename) {
        return 301 $uri/;
    }
}

Uma Boa Maneira de Depurar o Roteamento de Localização

Quando uma requisição chega ao lugar errado, reduza o problema a uma URL e um bloco server. Execute nginx -T para ver a configuração completa renderizada, incluindo arquivos incluídos, então procure por cada localização que poderia corresponder àquela URI. Preste atenção especial aos blocos regex porque sua ordem no arquivo importa.

Para arquivos estáticos, confirme o caminho do sistema de arquivos que o Nginx construirá a partir de root ou alias. Para requisições proxy, confirme se proxy_pass inclui uma parte de URI após o nome do upstream. Em seguida, recarregue somente depois que nginx -t passar.

Os blocos de localização são previsíveis uma vez que você internaliza as regras de prioridade, mas são implacáveis quando uma configuração cresce por copiar e colar. Use correspondências exatas para pequenos caminhos críticos, ^~ para diretórios que devem ignorar o tratamento regex, regex apenas onde a correspondência de padrões é genuinamente necessária e um simples location / como fallback claro.