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

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

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

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

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

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

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

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

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

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

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

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

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:

1. Procurar pelo nome exato (valdeir.dev);

2. Procurar pelo nome mais longo com o wildcard (*) como prefixo (*.valdeir.dev);

3. Procurar pelo nome mais longo com o wildcard (*) como sufixo (valdeir.*);

4. 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:

1. Verifica se o arquivo /var/www/html/upload/avatar.webp existe; se não existir,

2. Verifica se a pasta /var/www/html/upload/avatar.webp/ existe; se não existir,

3. Verifica se o arquivo /var/www/html/empty.gif existe; se não existir,

4. 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:

Série Nginx #3: Conheça as diretivas do NginxMedium