Exemplos da diretiva location no Nginx
A diretiva location do Nginx é uma ferramenta poderosa para controlar como diferentes tipos de requisições são processados. Ao definir regras em blocos location, você pode aplicar configurações específicas, redirecionar tráfego para diferentes partes da aplicação ou até bloquear completamente determinadas requisições. O uso correto dessa diretiva permite um gerenciamento eficiente das solicitações, o que é essencial para melhorar o desempenho, a segurança e a funcionalidade de aplicações web.
Sintaxe básica da diretiva location Copiar link
A diretiva location é definida no arquivo de configuração nginx.conf:
location [modifier] uri { ... }
-
modifier: parâmetro opcional que define o tipo de correspondência (exata, prefixo, expressão regular etc.)
-
uri: a URI que será comparada
Dentro das chaves, você pode definir diversas diretivas como proxy_pass, root ou index.
Exemplo de correspondência exata Copiar link
Uma correspondência exata ocorre quando a string fornecida coincide exatamente com a URI solicitada.
location = /exact-match {
root /var/www/html;
index index.html;
}
Somente requisições para /exact-match serão processadas por este bloco.
Você também pode adicionar condições usando if (observe que o Nginx não possui um if-else tradicional):
location = /exact-match {
root /var/www/html;
index index.html;
if ($http_user_agent ~* "Chrome") {
add_header X-Browser "Chrome";
}
}
Se o agente do usuário for identificado como Chrome, a resposta incluirá o cabeçalho adicional X-Browser.
Exemplo de correspondência por prefixo Copiar link
É o tipo mais comum e corresponde a qualquer URI que comece com a string especificada.
location /prefix {
root /var/www/html;
index index.html;
if ($request_method = POST) {
return 405;
}
}
Este bloco processará solicitações como /prefix/page1 ou /prefix/page2. Caso o método seja POST, o Nginx retorna 405 Method Not Allowed.
Exemplo com expressões regulares Copiar link
Para cenários mais complexos, expressões regulares são úteis.
Curingas comuns:
-
. – corresponde a um único caractere
-
.* – corresponde a qualquer sequência
-
^ – início da string
-
$ – fim da string
location ~* \.php$ {
fastcgi_pass 127.0.0.1:9000;
fastcgi_index index.php;
include fastcgi_params;
if ($request_uri ~* "/admin") {
return 403;
}
if ($request_uri !~* "/admin") {
add_header X-Admin "Not Admin";
}
}
Explicação:
-
~* indica regex sem distinção entre maiúsculas/minúsculas
-
\.php$ corresponde a arquivos PHP
-
se a URI contiver /admin, retorna 403
-
caso contrário, adiciona o header X-Admin
Correspondência sem distinção de maiúsculas Copiar link
location ~* \.jpg$ {
root /var/www/images;
if ($http_referer !~* "^https?://(www\.)?example\.com") {
return 403;
}
}
Corresponde a .jpg, .JPG etc., e só serve imagens se o referer vier de example.com.
Prioridade e ordem Copiar link
O Nginx avalia os blocos assim:
-
Correspondência exata (=)
-
Expressões regulares (~, ~*) em ordem de definição
-
Prefixos (/), onde o mais longo tem prioridade
Exemplo:
location = /exact { }
location ~* \.jpg$ { }
location / { }
Blocos location aninhados Copiar link
location /nested {
location /nested/subnested {
root /var/www/html;
}
root /var/www/html;
}
Solicitações para /nested/subnested usam o bloco interno.
Exemplo real de servidor web Copiar link
server {
listen 80;
server_name localhost;
location / {
root /var/www/html;
index index.html;
}
location = /about {
root /var/www/html;
index about.html;
}
location /api {
proxy_pass http://localhost:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
location ~ \.php$ {
root /var/www/html;
fastcgi_pass 127.0.0.1:9000;
fastcgi_index index.php;
include fastcgi_params;
}
location ~* \.(jpg|jpeg|png|gif|ico)$ {
root /var/www/images;
}
location /admin {
root /var/www/admin;
index index.html;
location /admin/stats {
proxy_pass http://localhost:8080/stats;
}
}
}
Recarregar o Nginx Copiar link
sudo systemctl reload nginx
Testes e depuração Copiar link
Validar configuração:
sudo nginx -t
Testar rotas:
curl -I http://localhost/about
curl -X POST http://localhost/prefix/form
curl -H "User-Agent: Chrome" http://localhost/exact-match
Ver logs:
tail -f /var/log/nginx/access.log
tail -f /var/log/nginx/error.log
Restringindo acesso a rotas sensíveis Copiar link
location /admin {
allow 192.168.1.100;
deny all;
}
Somente esse IP terá acesso.
root vs alias Copiar link
|
Diretiva |
Comportamento |
|
root |
acrescenta a URI |
|
alias |
substitui o prefixo |
Exemplo:
location /files/ {
alias /data/downloads/;
}
Nota: sempre finalize alias com /.
Conclusão Copiar link
Compreender bem a diretiva location é fundamental para controlar corretamente o processamento de requisições. Os diferentes tipos de correspondência — exata, prefixo e regex — possuem prioridades distintas e impactam diretamente o desempenho e comportamento do site. Ao dominar esses padrões e utilizar blocos aninhados, você pode criar configurações Nginx limpas, eficientes e seguras.