Exemplos da diretiva location no Nginx
Servidor web – Nginx
09.02.2026
Reading time: 5 min
Share
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
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
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
É 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
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
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
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
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
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
sudo systemctl reload nginx
Testes e depuração
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
location /admin {
allow 192.168.1.100;
deny all;
}
Somente esse IP terá acesso.
root vs alias
|
Diretiva |
Comportamento |
|
root |
acrescenta a URI |
|
alias |
substitui o prefixo |
Exemplo:
location /files/ {
alias /data/downloads/;
}
Nota: sempre finalize alias com /.
Conclusão
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.
Servidor web – Nginx
09.02.2026
Reading time: 5 min
Share
Semelhante
Tem perguntas,
comentários ou preocupações?
Nossos profissionais estão disponíveis para ajudá-lo a qualquer momento,
seja para assistência ou apenas se você não souber por onde começar.
seja para assistência ou apenas se você não souber por onde começar.
