Atualizar CSS e JavaScript guardados na cache do navegador

Se uma implementação alterar o CSS ou o JavaScript mas mantiver o mesmo URL, alguns navegadores podem reutilizar uma cópia ainda válida. Os cabeçalhos novos só são recebidos quando o navegador volta a pedir esse URL: o servidor não pode esvaziar à distância uma resposta que o cliente ainda considera recente.

Verifique primeiro em Rede / Network, nas ferramentas do navegador, que URL é carregado, o seu estado, Cache-Control, Age, ETag e se responde o navegador, um service worker ou uma CDN. Assim distingue a cache HTTP de outras camadas.

Altere o URL do recurso

A solução fiável é publicar cada versão com um URL novo. De preferência, utilize nomes com um hash do conteúdo:

<link rel="stylesheet" href="https://static.example.com/css/app.abc123.css">
<script src="https://static.example.com/js/app.abc123.js"></script>

Também pode adicionar uma versão ao URL, por exemplo /css/app.css?v=20260825, se a sua aplicação e as caches intermédias respeitarem os parâmetros de consulta.

Sirva o HTML sem versão com Cache-Control: no-cache para que seja revalidado e aponte para os recursos novos. no-cache permite guardar, mas exige validar antes de reutilizar. Mantenha ETag ou Last-Modified: permitem responder 304 Not Modified sem descarregar de novo um recurso idêntico.

Os recursos com hash podem usar uma expiração longa porque o seu URL muda com o conteúdo. Se existir uma CDN ou um service worker, atualize também o respetivo manifesto ou execute a purga específica dessa camada. Não mantenha durante semanas regras globais no-store, não elimine validadores e não use Pragma como substituto geral de Cache-Control.

Consulte o guia de cache HTTP e URLs com versão e a referência de Cache-Control.

Evitar que uma implementação estrague sessões abertas

Publique primeiro os ficheiros novos e depois o HTML que os referencia. Conserve durante um período de transição os recursos da versão anterior: um separador aberto pode continuar a pedi-los. Apagá-los de imediato pode provocar erros 404, mesmo que as visitas novas funcionem.

Se a aplicação utilizar um service worker, teste uma atualização com um separador antigo aberto e outro novo. O HTML dinâmico ou privado pode precisar de uma política diferente do HTML público; não aplique um cabeçalho global sem rever sessões e dados sensíveis.

Verifique o URL final, o conteúdo recebido e a versão depois da implementação. Uma resposta 304 pode ser correta quando o recurso não mudou; não é, por si só, um sintoma de cache defeituosa.