:Configure Nginx HTTP cache policies

Exemplos comuns de políticas de cache

Esta seção apresenta configurações de cache comuns para adicionar ao arquivo de configuração do Nginx em diferentes casos de uso. Todos os exemplos usam add_header ... always; para garantir a inclusão dos cabeçalhos de cache em todas as respostas, inclusive nas 304 Not Modified.

# Set long-term caching for static resources
# - For filenames that contain a content hash (e.g., main.a1b2c3d4.js), a 1-year cache with immutable is recommended.
location ~* "\.[a-f0-9]{8,}\.(css|js|png|jpg|jpeg|gif|svg|webp|ico|woff|woff2)$" {
    # For resources with hashes generated by build tools: cache for 1 year, browser never revalidates.
    add_header Cache-Control "public, max-age=31536003, immutable" always;
    access_log off;
}

# - For filenames that are fixed and rarely change (e.g., logo.png), use a 30-day cache.
location ~* \.(css|js|png|jpg|jpeg|gif|svg|webp|ico|woff|woff2)$ {
    # For general static resources without hashes: cache for 30 days, allows CDN and browser caching.
    add_header Cache-Control "public, max-age=2592000" always;
    access_log off;
}

# For directly requested HTML files
location ~* \.html$ {
    # Allows browser caching, but requires revalidation with the server before each use.
    # 'private' prevents intermediate proxies (like CDNs) from caching this response.
    # The server must provide an ETag or Last-Modified header to support validation.
    add_header Cache-Control "private, no-cache, must-revalidate" always;
}

# Example: For dynamic PHP scripts (adjust the path as needed)
location ~ \.php$ {
    # ... Other PHP-FPM configurations ...

    # Disable all caching: Browsers, proxies, and CDNs must not store the response.
    # 'no-store' is the strictest cache control directive.
    add_header Cache-Control "no-store" always;
}

Configuração de cache no lado do cliente (controle do navegador)

Controle o comportamento de cache do navegador do usuário adicionando os cabeçalhos Cache-Control e Expires à resposta HTTP. Essa prática reduz solicitações de rede e acelera o acesso dos usuários finais.

Diretivas principais

• Diretiva expires: Define tanto o cabeçalho Expires quanto o parâmetro max-age do cabeçalho Cache-Control.

  • Sintaxe: expires [time|epoch|max|off];

  • Exemplo: expires 30d; armazena em cache por 30 dias. Já expires -1; força o cliente a revalidar o recurso com o servidor antes de usar a versão em cache. Equivale a Cache-Control: no-cache, mas ainda permite o armazenamento do recurso em cache.

  • Observação: A diretiva add_header oferece controle mais granular e é o método de configuração recomendado.

• Diretiva add_header: Adiciona um cabeçalho HTTP específico à resposta.

  • Sintaxe: add_header <name> <value> [always];

  • Descrição do parâmetro always: Por padrão, add_header aplica-se apenas a respostas 2xx e 3xx. Em respostas 304 Not Modified, o Nginx não adiciona automaticamente cabeçalhos personalizados. Embora o navegador utilize a política de cache da resposta 200 inicial, adicione o parâmetro always ao cabeçalho de controle de cache. Isso garante clareza e compatibilidade ao aplicar o cabeçalho a todos os códigos de status de resposta.

Descrição dos valores-chave do Cache-Control

• public: Qualquer cache pode armazenar a resposta, incluindo navegadores, CDNs e servidores proxy.

• private: Apenas o navegador do usuário final pode armazenar a resposta em cache. Caches compartilhados, como CDNs, ficam proibidos. Indicado para conteúdo com informações específicas do usuário.

• no-cache: Exige que o cliente envie uma solicitação de validação ao servidor antes de cada uso de uma cópia em cache. Se o recurso não tiver sido alterado, o servidor retorna 304 Not Modified e o cliente usa o cache local. Economiza largura de banda.

• no-store: Proíbe navegadores e servidores proxy de armazenarem qualquer parte da resposta. Adequado para dados altamente sensíveis.

• max-age=<seconds>: Define o período de validade do cache em segundos.

• immutable: Informa ao navegador que o conteúdo do recurso não mudará durante seu tempo de vida útil. O navegador pode ignorar a solicitação de validação para esse recurso, mesmo quando o usuário atualizar totalmente a página. Ideal para arquivos com hashes de versão nos nomes.

Implantar e verificar

1. Edite a configuração. Adicione o bloco location ao bloco server do seu site. O arquivo de configuração geralmente reside em /etc/nginx/conf.d/ ou /etc/nginx/sites-enabled/.

2. Recarregue a configuração.

   sudo nginx -t && sudo nginx -s reload

3. Verifique os cabeçalhos de resposta. Use curl para confirmar se os cabeçalhos de cache estão ativos. Esse método ignora o cache do navegador.

   curl -I http://your-domain.com/path/to/file.js

   A saída deve incluir os cabeçalhos esperados, como Cache-Control: public, max-age=31536000.

4. Verifique o comportamento 304 (se ETag ou no-cache estiver configurado). Teste enviando manualmente um cabeçalho de validação:

   ETAG=$(curl -I http://example.com/file.js 2>/dev/null | grep -i etag | cut -d' ' -f2 | tr -d '\r')
   curl -H "If-None-Match: $ETAG" -I http://example.com/file.js  # Expect a 304 response

5. Verifique no navegador.

   1. Acesse Developer Tools → painel Network.

   2. Marque a caixa Disable cache para ver o carregamento inicial (deve apresentar status 200 OK).

   3. Desmarque a caixa e atualize a página:

      1. Nenhuma solicitação ou from cache aparece. Isso indica um acerto forte de cache.

      2. 304 aparece. Isso indica um acerto condicional de cache.

Política de atualização de cache

Para garantir que os usuários recebam os recursos estáticos mais recentes, como style.css, incorpore um hash de conteúdo ou número de versão no nome do arquivo. Essa técnica chama-se cache busting.

• Manual: style.v2.css

• Automática (recomendada): style.a1b2c3d4.css. Gerada por ferramentas de build como Webpack ou Vite.

FAQ

# In the http block
map $sent_http_content_type $cache_control {
    ~^image/    "public, max-age=2592000";
    text/css    "public, max-age=2592000";
    application/javascript "public, max-age=2592000";
    default     "no-cache";
}

# In the server block
add_header Cache-Control $cache_control always;