Diretivas do Nginx
De acordo com a documentação oficial, o nginx consiste em módulos controlados por diretivas especificadas nos arquivos de configuração. Elas são divididas em diretivas simples e diretivas em bloco.
Uma diretiva simples consiste no nome e nos parâmetros separados por espaços e com um ponto e vírgula (;
) no final.
Uma diretiva de bloco permite que o desenvolvedor utilize outras diretivas dentro de chaves ({
e }
). Quando isso ocorre, essa diretiva de bloco é chamada de contexto (exemplos: events
, http
, server
e location
).
Diretiva add_header
add_header
A diretiva add_header
é usada para adicionar cabeçalhos HTTP nas respostas do servidor. É muito útil para configurar cabeçalhos CORS, entre outros.
Sintaxe:
add_header name value [always];
Exemplo de uso:
location /upload {
add_header "Access-Control-Allow-Origin" "https://*.valdeir.dev";
add_header "Access-Control-Allow-Methods" "GET, OPTIONS";
add_header X-Dev "Valdeir Psr" always;
}
Diretiva alias
alias
A diretiva alias
é usada para modificar a localização do diretório especificado na diretiva root
.
Sintaxe:
alias path;
Exemplo de uso:
location /css {
alias /dev/vda2/css/;
}
Este exemplo significa que a requisição para https://valdeir.psr/css/global.css
carregará os arquivos de /dev/vda2/css/
.
Diretiva client_max_body_size
client_max_body_size
Esta diretiva configura o tamanho máximo do corpo de uma requisição, útil para limitar o tamanho dos uploads.
Sintaxe:
client_max_body_size size;
Exemplo de uso:
client_max_body_size 1G;
Diretiva error_page
error_page
Permite customizar páginas de erro.
Sintaxe:
error_page code ... [=[response]] uri;
Exemplo de uso:
error_page 404 /not_found.html;
error_page 500 502 503 504 /50x.html;
error_page 401 =200 https://auth.$server_name;
Diretiva listen
listen
Define o endereço e/ou porta que o Nginx deve escutar.
Sintaxe:
listen address[:port] [default_server] [ssl] [http2];
listen port [default_server] [ssl] [http2];
Exemplo de uso:
listen 80;
listen [::]:80;
listen 443 ssl;
listen [::]:443 ssl;
Diretiva location
location
Usada para aplicar configurações baseadas na URI da requisição.
Sintaxe:
location [ = | ~ | ~* | ^~ ] uri { ... }
location @name { ... }
Exemplo de uso:
location = /upload {
# Aplica apenas se a URI for exatamente /upload
}
location ~* /upload/.*\.(jpe?g|gif|webp)$ {
# Aplica a URIs que correspondem ao padrão regex, insensível a maiúsculas/minúsculas
}
Diretiva map
map
Cria variáveis baseadas em valores chave-valor.
Sintaxe:
map $variable_nginx $variable_name { ... }
Exemplo de uso:
map $http_user_agent $ua_blocked {
default 0;
~Jorgee 1;
~ZmEu 1;
~*Spam 1;
~*Scan 1;
Scanner 1;
Wget 1;
curl 1;
}
server {
if ($ua_blocked) {
return 403;
}
}
Vamos expandir a documentação incluindo detalhes adicionais sobre outras diretivas importantes do Nginx que podem ser usadas para aprimorar a configuração e gestão de seu servidor web:
Diretiva rewrite
rewrite
A diretiva rewrite
é usada para reescrever URIs de requisições internamente ou para redirecionar o usuário externamente usando códigos de status 301 ou 302.
Sintaxe:
rewrite regex replacement [flag];
Exemplo de uso:
location /oldsite {
rewrite ^(/oldsite/.*)$ /newsite/$1 permanent;
}
Este exemplo redireciona usuários do caminho /oldsite
para /newsite
usando um redirecionamento permanente (301).
Diretiva proxy_pass
proxy_pass
A diretiva proxy_pass
é usada para redirecionar requisições para outro servidor.
Sintaxe:
proxy_pass http://backendserver_url;
Exemplo de uso:
location /app {
proxy_pass http://127.0.0.1:3000;
}
Este exemplo redireciona todas as requisições para /app
para um servidor rodando na porta 3000 no localhost.
Diretiva try_files
try_files
A diretiva try_files
tenta entregar o arquivo requisitado pela URI, se não encontrar, tenta a próxima opção até encontrar uma correspondência válida ou retornar um erro.
Sintaxe:
try_files file1 file2 ... uri_or_error_code;
Exemplo de uso:
location /images {
try_files $uri $uri/ /default.png;
}
Esse exemplo tenta servir o arquivo solicitado em /images
, se não existir, serve default.png
.
Diretiva gzip
gzip
A diretiva gzip
habilita ou desabilita a compressão gzip para respostas.
Sintaxe:
gzip on|off;
Exemplo de uso:
gzip on;
gzip_types text/plain application/xml text/css application/javascript;
gzip_vary on;
Este exemplo ativa a compressão gzip para tipos de conteúdo específicos e utiliza o cabeçalho Vary
para auxiliar os proxies a gerenciar a cache corretamente.
Diretiva ssl_certificate
e ssl_certificate_key
ssl_certificate
e ssl_certificate_key
Essas diretivas especificam o caminho para o certificado SSL e sua chave privada, respectivamente.
Sintaxe:
ssl_certificate /caminho/para/certificado.pem;
ssl_certificate_key /caminho/para/chave_privada.key;
Exemplo de uso:
ssl_certificate /etc/nginx/ssl/meusite.pem;
ssl_certificate_key /etc/nginx/ssl/meusite.key;
Este exemplo configura o Nginx para usar um certificado SSL específico e sua chave.
server (fonte)
Essa diretiva em bloco serve para criar um servidor virtual.
# Syntax: server { ... }
# Default: —
# Context: http
#
server {
server_name valdeir.dev www.valdeir.dev;
}
server_name (fonte)
Define o nome/URL do servidor virtual criado. É possível definir mais de um nome quando separados por espaços. A diretiva, assim como rewrite
e location
, permite o uso de expressões regulares.
Criaremos abaixo um servidor virtual que receberá as requisições das URLS:
valdeir.dev
cdn.valdeir.dev
assets.valdeir.dev
qualquer-coisa.valdeir.cdn
server {
# Syntax: server_name name ...;
# Default: server_name "";
# Context: server
#
server_name valdeir.dev ~(cdn|assets)\.valdeir\.dev$ *.valdeir.cdn;
}
Atenção! Para utilizar RegExp, é necessário que o Nginx tenha sido compilado com suporte à biblioteca PCRE
.
Através da diretiva server_name
, você pode criar variáveis de acordo com os grupos capturados na sua expressão regular.
server {
server_name ~^(www\.)?(?<domain>.+)$;
location / {
root /sites/$domain;
}
}
server {
server_name _;
location / {
root /sites/default;
}
}
Ordem na busca pelos servidor
Quando há mais de um nome de servidor, o Nginx seguirá a seguinte ordem:
Procurar pelo nome exato (valdeir.dev);
Procurar pelo nome mais longo com o wildcard (
*
) como prefixo (*.valdeir.dev);Procurar pelo nome mais longo com o wildcard (
*
) como sufixo (valdeir.*);Procurar pela primeira ocorrência usando expressão regular.
try_files (fonte)
Essa diretiva verificará se um arquivo existe seguindo a ordem pré-definida pelo administrador. O processamento é feito semelhante ao das diretivas alias
e root
. Ela permite também que o cliente possa acessar uma pasta quando o valor terminar com uma barra (/
). Isso é útil quando o desenvolvedor utiliza a diretiva autoindex
. Se arquivo nenhum for encontrado, o o usuário será redirecionado para outra página, URL ou bloco location
nomeado.
root /var/www/html;
autoindex on;
location /upload {
# Syntax: try_files file ... uri;
# try_files file ... =code;
# Default: —
# Context: server, location
#
try_files $uri $uri/ /empty.gif =444;
}
No exemplo acima, ao acessar a requisição /upload/avatar.webp
, o Nginx seguirá a seguinte ordem:
Verifica se o arquivo
/var/www/html/upload/avatar.webp
existe; se não existir,Verifica se a pasta
/var/www/html/upload/avatar.webp/
existe; se não existir,Verifica se o arquivo
/var/www/html/empty.gif
existe; se não existir,Fecha a conexão sem uma resposta (usando o
=444
).
É possível também utilizar bloco location
nomeado.
location / {
try_files $uri $uri/ @opencart;
}
location @opencart {
rewrite ^/sitemap.xml$ /index.php?route=extension/feed/google_sitemap last;
rewrite ^/googlebase.xml$ /index.php?route=extension/feed/google_base last;
rewrite ^/system/storage/(.*) /index.php?route=error/not_found last;
rewrite ^/(.+)$ /index.php?_route_=$1 last;
}
location ~* (\.twig|\.tpl|\.ini|\.log|(?<!robots)\.txt)$ {
deny all;
}
Mais Informações:
Last updated