Cabeçalhos de Cache HTTP Cache-Control, ETag e max-age sem suposições

Cada resposta HTTP que você envia é ou é cacheada ou não — e se você não for deliberado sobre isso, o navegador decide por si mesmo. O resultado é geralmente uma mistura de cache agressivo para coisas que mudam com frequência e nenhum cache para coisas que mudam raramente. Ambos prejudicam seus usuários.

Este guia fornece o modelo mental para definir corretamente os cabeçalhos de cache HTTP pela primeira vez: o que cada diretiva controla, como os ETags acionam a revalidação e como escolher TTLs que sobrevivem às deploys sem servir conteúdo obsoleto.

Como o cache do navegador realmente funciona

Quando um navegador solicita um recurso, ele verifica primeiro seu cache local. Se uma cópia cacheada fresca existir, ele a serve imediatamente — sem nenhuma requisição de rede. Se a cópia cacheada pode estar desatualizada, ele envia uma requisição condicional para a origem. A origem confirma se o recurso não mudou (304 Not Modified) ou envia a resposta atualizada completa (200 OK).

CDNs estão no meio desse ciclo de vida. Eles armazenam respostas mais próximas dos usuários geograficamente e obedecem aos mesmos cabeçalhos de cache HTTP — com algumas extensões específicas de CDN, como s-maxage.

Três perguntas determinam o comportamento de cache:

• Este resposta é cacheável em algum momento? Controle por Cache-Control: no-store ou private
• Por quanto tempo é fresco? Controle por max-age ou s-maxage
• Como a desatualização é validada? Controle por ETags ou Last-Modified

diretivas do cabeçalho Cache-Control

O Cache-Control o cabeçalho é a principal forma de declarar a política de cache. Várias diretivas são separadas por vírgula. Aqui está o que cada uma faz realmente:

max-age

max-age=N informa os caches (navegador e CDN) por quantos segundos a resposta permanece fresca. Uma resposta com max-age=86400 é considerada fresca por exatamente 24 horas a partir do momento em que foi recebida. Após isso, o cache deve revalidar antes de servir novamente.

Para ativos estáticos com nomes de arquivo versionados (como main.abc123.js), um ano inteiro é comum: max-age=31536000. Para documentos HTML, uma janela muito curta — ou nenhum cache — é mais seguro, já que os documentos HTML referenciam esses ativos versionados.

s-maxage

s-maxage sobrescreve max-age para caches compartilhados (CDNs, servidores de proxy) apenas. O navegador ignora isso. Isso permite servir respostas longamente cacheadas aos usuários enquanto mantém o edge do CDN mais fresco. Um padrão típico é Cache-Control: public, max-age=3600, s-maxage=86400 — o navegador cacheia por 1 hora, o CDN cacheia por 24 horas.

no-cache

no-cache não significa "não cacheie". Significa que o cache deve revalidar com a origem antes de servir a resposta armazenada, mesmo que ainda esteja fresca. A resposta é cacheada, mas cada uso exige uma viagem de volta para verificar se ainda é válida. Isso é apropriado para conteúdo que muda com frequência, mas que se beneficia com as economias de banda de uma resposta 304.

no-store

no-store é a única diretiva que realmente impede o cache. Nenhum cache do navegador, nenhum cache do CDN, nenhuma gravação em disco. Use para respostas contendo dados sensíveis do usuário — extratos bancários, registros médicos, tokens. Não use como padrão porque você ainda não pensou sobre o cache.

public e private

public permite explicitamente que caches compartilhados (CDNs) armazenem a resposta, mesmo quando a requisição tiver um Authorization cabeçalho. private restringe o cache apenas ao navegador do usuário final — os CDNs não devem armazená-lo. Para respostas autenticadas que são específicas do usuário, private impede que a resposta de um usuário seja servida a outro.

must-revalidate

must-revalidate impede que os caches servam respostas desatualizadas quando não conseguem alcançar a origem. Sem isso, um cache pode servir uma resposta expirada se a rede estiver indisponível. Com isso, a requisição falha com um 504 se a origem não for alcançável. Use para conteúdo onde servir dados desatualizados é pior do que um erro.

ETags: revalidação precisa

Um ETag é um identificador gerado pelo servidor para uma versão específica de um recurso — pense nele como um impressão digital do corpo da resposta. O servidor envia isso na resposta:

ETag: "abc123def456"

Quando a cópia cacheada expira, o navegador envia uma requisição condicional com o ETag armazenado:

If-None-Match: "abc123def456"

Se o recurso não mudou, o servidor responde com 304 Not Modified e um corpo vazio — economizando banda enquanto ainda confirma a frescor. Se mudou, o servidor responde com 200 OK e o novo ETag.

ETags fortes vs fracos

A ETag forte ("abc123") significa que a resposta é idêntica byte a byte. Um ETag fraco (W/"abc123") significa que as respostas são semanticamente equivalentes, mas podem diferir em detalhes triviais como espaços em branco ou ordem de cabeçalhos. ETags fracos podem ser gerados com mais eficiência, mas não podem ser usados em requisições de intervalo. A menos que você tenha uma razão específica para usar ETags fracos, use os fortes.

Last-Modified: a alternativa mais antiga

Antes dos ETags, os servidores usavam Last-Modified marcadores de tempo para revalidação. O servidor envia:

Last-Modified: Thu, 01 May 2026 12:00:00 GMT

O navegador revalida com:

If-Modified-Since: Thu, 01 May 2026 12:00:00 GMT

O servidor retorna 304 se o recurso não mudou desde aquele marcador de tempo.

A fraqueza: os marcadores de tempo têm uma precisão de um segundo. Um arquivo modificado duas vezes dentro do mesmo segundo será considerado inalterado. Os ETags lidam com isso corretamente e são preferidos. A maioria dos frameworks modernos envia ambos — o navegador usa o que estiver disponível, com os ETags tendo prioridade.

Quebrar cache sem quebrar deploys

Um longo max-age em um ativo estático é seguro apenas se a URL muda quando o conteúdo muda. Existem duas estratégias:

Fingerprinting da URL (recomendado)

Inclua um hash do conteúdo do arquivo no nome do arquivo: main.a1b2c3d4.js. Quando o arquivo muda, o hash muda, a URL muda e o navegador obtém o novo arquivo — evitando o cache inteiramente. A antiga URL permanece no cache, mas nunca é solicitada novamente uma vez que o HTML referenciar a nova URL.

Webpack, Vite e a maioria dos bundlers modernos fazem isso automaticamente. O padrão permite que você defina Cache-Control: public, max-age=31536000, immutable — a immutable diretiva informa ao navegador para não se preocupar em revalidar mesmo que a entrada no cache esteja tecnicamente desatualizada.

Query strings (menos confiável)

Agrega uma versão na URL como uma query string (main.js?v=1.2.3) tecnicamente cria uma URL diferente, mas alguns CDNs e proxies ignoram query strings ao construir chaves de cache. O fingerprinting da URL no caminho é mais confiável e universalmente suportado.

Erros comuns que prejudicam o cache

Cache de respostas de API que não deveriam ser cacheadas

APIs JSON que retornam dados específicos do usuário ou sensíveis ao tempo devem usar Cache-Control: no-store ou, pelo menos, private, no-cache. Um erro comum é deixar um CDN cachear uma resposta como /api/user/profile e servir os dados de um usuário para outro. Se sua API não define um Cache-Control cabeçalho, alguns CDNs irão cacheá-lo mesmo assim usando heurísticas.

Esquecer Vary: Accept-Encoding

Se seu servidor serve versões comprimidas e não comprimidas de um recurso dependendo do cabeçalho do cliente Accept-Encoding , o cache deve armazenar cópias separadas para cada variante. Sem Vary: Accept-Encoding, um CDN pode armazenar a versão gzip e servir para um cliente que não suporta gzip — ou vice-versa. Defina sempre quando a compressão for condicional.

Usar no-cache quando quer dizer no-store

Desenvolvedores muitas vezes escrevem Cache-Control: no-cache quando querem impedir o cache totalmente, mas no-cache ainda armazena a resposta — ela só exige revalidação antes de cada uso. Use no-store quando você realmente não quer que a resposta seja persistida em qualquer lugar.

Definir max-age em HTML sem uma estratégia de quebra de cache

Documentos HTML referenciam ativos versionados. Se você cacheia seu HTML com um longo max-age, os usuários não pegarão os novos nomes de arquivos após um deploy — eles continuarão executando o antigo HTML, que referencia os antigos hashes. Defina um TTL curto (ou no-cache) para HTML e reserve TTLs longos para os ativos imutáveis que o HTML referencia.

Calcule seu intervalo de expiração antes de lançar

Escolher um max-age valor é mais fácil quando você pode visualizar o que significa em tempo real. O Calculadora de TTL / max-age de Cache HTTP em iotools.cloud permite que você entre um TTL em segundos e veja a data exata de expiração. Útil para verificar valores como 86400 (24 horas), 2592000 (30 dias) ou 31536000 (1 ano) antes de cometer esses valores em sua configuração de servidor ou regras do CDN.

Uma lista prática de políticas de cache

• Documentos HTML: Cache-Control: no-cache — revalidar sempre, beneficiar-se de 304s quando nada mudou
• Ativos estáticos versionados (JS, CSS, imagens com hash no nome do arquivo): Cache-Control: public, max-age=31536000, immutable
• Ativos estáticos não versionados (fontes, favicon): Cache-Control: public, max-age=604800 (1 semana)
• Respostas de API (públicas, sensíveis ao tempo): Cache-Control: public, max-age=60, s-maxage=300 — TTL curto no navegador, TTL mais longo no CDN
• Respostas de API (específicas ao usuário): Cache-Control: private, no-cache
• Dados sensíveis: Cache-Control: no-store
• Sempre defina Vary: Accept-Encoding quando servir respostas comprimidas condicionalmente

ETags devem estar ativos por padrão para qualquer coisa que você esteja cacheando — eles são o mecanismo que torna a revalidação eficiente em termos de banda. A maioria dos servidores web (Nginx, Apache, Caddy) gera ETags automaticamente a menos que você os desative.

Você também pode gostar