Atualizar JavaScript e CSS sem deixar versões antigas na cache

Separe o HTML dos recursos versionados

Considere o HTML um manifesto. A versão A referencia app.4c21.js e site.19ab.css; B referencia app.9d80.js e pode manter o CSS se os bytes não mudaram. Estes nomes são exemplos, não hashes calculados.

Assim, recursos iguais são reutilizados e os alterados ganham outra identidade. Guardar HTML durante um ano pode atrasar a descoberta da publicação: o documento antigo continua a pedir os endereços antigos.

Aplique cabeçalhos adequados a cada recurso

Para um ficheiro público que nunca muda naquele endereço, max-age longo e immutable podem ser adequados. No HTML, no-cache permite guardar, mas exige validação antes da reutilização. no-store pede que a resposta não seja guardada. Não aplique uma única regra a tudo.

Os cabeçalhos apresentados ilustram uma estratégia. Verifique o que o alojamento realmente envia e como está configurada a cache da CDN. Uma definição local não prova a política recebida publicamente.

Versioned public asset: /assets/app.9d80.js
Cache-Control: public, max-age=31536000, immutable

HTML document: /index.html
Cache-Control: no-cache

The URL /assets/app.9d80.js must continue to serve the same bytes.

Confirme que a chave inclui a consulta

/app.js?v=release-b pode ter identidade diferente de /app.js?v=release-a se todas as caches relevantes incluírem o parâmetro na chave. Uma regra CDN que ignore consultas pode tratar ambos como o mesmo objeto.

Evite valores aleatórios a cada visita: destroem a reutilização. Use hash ou versão estável que só mude com o conteúdo. Fragmentos como /app.js#release-b não são enviados no pedido HTTP e não servem para versionar a resposta.

Encontre a camada que ainda entrega conteúdo antigo

Compare HTML, endereço referenciado e bytes recebidos. Se o HTML aponta para o hash antigo, investigue a sua validade. Se aponta para o novo mas recebe bytes velhos, examine publicação, chaves e origem. Se a rede está correta, procure uma página ainda em execução ou um service worker.

Limpar a CDN não apaga uma resposta válida já guardada no navegador de cada visitante. Uma recarga forçada é apenas um diagnóstico local. Anote a camada ignorada em cada teste para tornar o resultado reproduzível.

• Registe o endereço final do HTML e do script ou CSS.
• Inspecione estado, Content-Type, Cache-Control, ETag e cabeçalhos de cache.
• Confirme os bytes esperados, não uma página HTML de recurso alternativo.
• Verifique separadamente a cache do service worker, quando existir.
• Teste uma visita limpa e uma página aberta durante a publicação.

Preserve páginas antigas e a possibilidade de reversão

Envie novos recursos antes do HTML que os referencia ou publique o conjunto de forma atómica. Guarde versões antigas durante o período necessário para documentos em cache e separadores abertos; módulos podem ser pedidos horas depois.

Publique B com recursos de A e B presentes, verifique B e mantenha a possibilidade de voltar a A. Apagar app.4c21.js de imediato quebra páginas antigas. Reutilizar o nome com bytes novos viola o contrato e torna a reversão imprevisível.

Meça reutilização depois de confirmar a correção

Teste a primeira visita, uma repetição e uma nova publicação: transferência inicial, reutilização elegível e descarga apenas dos recursos alterados. Inspecione transferências reais, incluindo pedidos de revalidação.

As calculadoras de poupança de cache e transferência comparam hipóteses explícitas sobre acertos, pedidos e tamanho. Não substituem medir os cabeçalhos públicos e a taxa real de acertos.