Cache-Control informa como caches HTTP podem guardar e reutilizar uma resposta. Atualizar um arquivo no servidor não obriga o navegador a buscá-lo imediatamente: uma cópia ainda considerada fresca pode continuar sendo usada, conforme a política recebida antes.
Para investigar uma versão antiga, identifique qual URL foi solicitada, qual camada respondeu e quais cabeçalhos acompanharam a resposta. Navegador, intermediário e servidor de origem podem participar de caminhos diferentes.
Neste artigo
A URL continua igual, mas a cópia pode estar fresca
Considere uma folha de estilos entregue com:
Cache-Control: max-age=3600
Dentro das condições de validade e idade dessa resposta, o cache pode reutilizá-la sem perguntar ao servidor a cada acesso. Se você substituir o arquivo mantendo a URL, o cliente não recebe automaticamente a notícia da mudança.
O guia de cache HTTP da MDN distingue armazenamento, frescor e revalidação. Essas etapas não devem ser resumidas à ideia de que o cache está “ligado” ou “desligado”.
no-cache permite guardar, mas exige conferir
O nome costuma causar confusão. Sem qualificações adicionais, no-cache permite armazenar a resposta, mas exige validá-la antes da reutilização. no-store instrui a não armazenar a resposta. As condições são descritas pelo RFC 9111.
| Diretiva no exemplo | Ideia central |
|---|---|
max-age=3600 |
A resposta pode permanecer fresca pelo intervalo indicado, consideradas as regras de idade |
no-cache |
A cópia guardada precisa de validação antes de ser reutilizada |
no-store |
A resposta não deve ser armazenada pelos caches |
private |
Armazenamento restrito a cache privado, em vez de compartilhado |
must-revalidate |
Uma resposta que ficou obsoleta não pode ser reutilizada sem validação nas condições definidas |
Não confunda must-revalidate com a obrigação de consultar o servidor enquanto a resposta ainda está fresca. Também não trate no-store como uma ordem que apaga retroativamente todas as cópias anteriores ou como substituto de autorização e transporte seguro.
Um validador permite conferir sem baixar tudo novamente
O servidor pode associar uma representação a um ETag, um identificador usado na validação. Quando já possui a cópia, o cliente pode enviar esse identificador em If-None-Match.
Se a representação ainda corresponder, uma resposta 304 Not Modified permite reutilizar o corpo guardado, sem um novo corpo na resposta. Se mudou, o servidor pode entregar 200 com o conteúdo atualizado e outro identificador. A referência de Cache-Control da MDN relaciona essas diretivas ao processo de validação.
O ETag não precisa ser lido pelo usuário como uma data ou interpretado como uma prova criptográfica. No exemplo a seguir, usamos identificadores simples escolhidos pelo servidor da demonstração.
Três requisições num ensaio local
Executamos um servidor HTTP de teste acessível apenas em loopback. Ele usou Cache-Control: no-cache, respondeu a três requisições e foi encerrado. A sequência observada foi:
| Requisição | Estado do servidor | Resposta |
|---|---|---|
| GET inicial | Conteúdo versao-1, ETag "v1" |
200, com o corpo versao-1 |
GET com If-None-Match: "v1" |
Sem mudança | 304, sem corpo novo |
GET com If-None-Match: "v1" |
Conteúdo alterado para versao-2, ETag "v2" |
200, com o corpo novo |
Os cabeçalhos centrais da segunda requisição foram:
If-None-Match: "v1"
E a resposta correspondente incluiu:
HTTP/1.0 304 Not Modified
ETag: "v1"
Cache-Control: no-cache
O ensaio confirma a troca condicional implementada nesse servidor. Não implementa um cache automático de navegador nem mede CDN, tráfego de produção ou tempo economizado. A cópia anterior e sua validação são conceitos separados mesmo quando a interface final não mostra esse percurso.
Um intermediário pode continuar entregando outra versão
Se houver cache compartilhado, compare a resposta que chega ao cliente com a política aplicada nessa camada. Configurações próprias do provedor e diretivas voltadas a caches compartilhados precisam ser consideradas junto do cabeçalho observado.
Não conclua que limpar o navegador corrigiu o servidor, ou que limpar uma CDN removeu uma cópia ainda fresca no cliente. Uma camada pode voltar a guardar o conteúdo recebido de outra. Anote o caminho e confira o resultado depois da alteração.
Para conteúdo personalizado, a chave de cache e a política de compartilhamento também importam. Uma resposta correta para um usuário pode ser inadequada para outro; tratar apenas a atualização visual deixa de fora esse problema.
Arquivos com versão na URL ajudam, mas o HTML também precisa mudar
Um nome como app.a1b2c3.css permite associar uma versão a uma URL nova. O arquivo anterior pode continuar em cache sem ser confundido com o novo nome. Essa estratégia depende de publicar a referência correta no HTML ou no manifesto que o cliente recebe.
Se o próprio HTML permanecer antigo numa camada de cache, continuará apontando para a versão anterior. Colocar um nome novo no servidor não corrige uma referência que não foi atualizada. Da mesma forma, acrescentar um parâmetro à URL não garante que toda configuração intermediária o trate como uma chave distinta.
Um registro para encontrar a camada responsável
Abra as ferramentas de rede e confira URL, status, cabeçalhos e conteúdo recebido. Registre se houve nova requisição, validação ou reutilização local. Compare com a versão esperada na origem, respeitando o caminho real de produção.
Depois, altere a política ou a invalidação da camada identificada e repita a mesma leitura. Confirme tanto o documento que aponta para o arquivo quanto o próprio recurso. Preserve a evidência da resposta anterior para verificar se a nova política resolveu a entrega antiga sem ampliar desnecessariamente o número de downloads.