Receita: cache e PWA
Cabeçalhos de cache para arquivos estáticos e um service worker conservador com página offline.
Neste texto
Que problema esta receita resolve?
Visitantes recorrentes baixam de novo CSS, JavaScript, fontes e imagens que não mudaram. Isso gasta banda e atrasa a página. Ao mesmo tempo, o cache mal configurado é fonte clássica de erro: o visitante vê um preço velho, o administrador edita e nada muda, ou o carrinho mostra os itens de outra pessoa. A receita separa o que pode ficar guardado por muito tempo do que precisa ser sempre conferido.
A lógica vem de um plugin que combina cache interno e PWA, desenvolvido por Camillo Dantas e não vendido. Aqui está o método com código.
Quando usar e quando não usar
Use cabeçalhos de cache em qualquer site com arquivos estáticos versionados. Use o service worker quando o site é majoritariamente de leitura (blog, documentação, páginas institucionais) e quando uma página offline tem valor.
Não use:
- service worker em loja, área de membros ou painel com sessão, a menos que você domine as exceções;
immutableem arquivos sem versão na URL;- cache de HTML por tempo longo sem estratégia de invalidação.
Pré-requisitos
- HTTPS ativo. Service workers só funcionam em contexto seguro (localhost incluído para desenvolvimento), segundo o MDN.
- Acesso ao
.htaccess(Apache) ou à configuração do servidor. - Arquivos estáticos com versão na URL. O WordPress acrescenta
?ver=a scripts e estilos registrados corretamente, o que serve como versão. - Nível: avançado.
Passo a passo
- 01Defina a política: estáticos com cache longo, HTML sempre revalidado.
- 02Aplique os cabeçalhos no servidor.
- 03Crie o service worker com rede primeiro para páginas e cache para estáticos.
- 04Registre o worker e crie a página offline.
- 05Teste o ciclo de atualização e a área logada.
Camada 1: cabeçalhos no Apache
O MDN indica Cache-Control: max-age=31536000, immutable para arquivos com URL que muda quando o conteúdo muda, e Cache-Control: no-cache para o HTML de entrada, que assim é revalidado a cada uso (e responde 304 se nada mudou). Adicione ao .htaccess, antes do bloco do WordPress:
<IfModule mod_headers.c>
<FilesMatch "\.(css|js|woff2|webp|avif|png|jpg|jpeg|svg)$">
Header set Cache-Control "public, max-age=31536000, immutable"
</FilesMatch>
<FilesMatch "\.(html|php)$">
Header set Cache-Control "no-cache"
</FilesMatch>
</IfModule>
Atenção: este bloco assume que seus CSS e JS têm versão na URL. Se o tema serve estilo.css sem versão, a mudança fica invisível por um ano. Corrija o registro do arquivo com wp_enqueue_style( 'tema', $url, array(), filemtime( $caminho ) ), que muda o ?ver= a cada edição.
No Nginx, o equivalente é location ~* \.(css|js|woff2|webp|avif|png|jpe?g|svg)$ { add_header Cache-Control "public, max-age=31536000, immutable"; }. Um plugin de cache de página, quando existe, também gera cabeçalhos; não duplique a regra.
Camada 2: service worker conservador
Coloque sw.js na raiz pública do site (escopo /). Estratégia: rede primeiro para navegação, com cópia offline só da página /offline/; cache primeiro para estáticos do próprio domínio.
const VERSAO = "v1";
const CACHE = "estaticos-" + VERSAO;
const OFFLINE = "/offline/";
self.addEventListener("install", (e) => {
e.waitUntil(caches.open(CACHE).then((c) => c.addAll([OFFLINE])));
self.skipWaiting();
});
self.addEventListener("activate", (e) => {
e.waitUntil(
caches.keys().then((chaves) =>
Promise.all(chaves.filter((k) => k !== CACHE).map((k) => caches.delete(k)))
)
);
self.clients.claim();
});
self.addEventListener("fetch", (e) => {
const req = e.request;
const url = new URL(req.url);
// Só GET do mesmo domínio; nunca admin, login, API, preview.
if (req.method !== "GET" || url.origin !== location.origin) return;
if (/^\/(wp-admin|wp-login|wp-json|carrinho|checkout|minha-conta)/.test(url.pathname)) return;
if (url.searchParams.has("preview")) return;
// Navegação: rede primeiro, página offline se falhar.
if (req.mode === "navigate") {
e.respondWith(fetch(req).catch(() => caches.match(OFFLINE)));
return;
}
// Estáticos: cache primeiro.
if (/\.(css|js|woff2|webp|avif|png|jpe?g|svg)$/.test(url.pathname)) {
e.respondWith(
caches.match(req).then((achado) => {
if (achado) return achado;
return fetch(req).then((resp) => {
if (resp.ok) {
const copia = resp.clone();
caches.open(CACHE).then((c) => c.put(req, copia));
}
return resp;
});
})
);
}
});
Pontos conferidos no guia do MDN: event.waitUntil() segura a instalação até a promessa resolver; caches.keys() no activate remove versões antigas; a resposta é clonada antes de gravar, porque corpos de resposta só são lidos uma vez; skipWaiting() e clients.claim() ativam a nova versão sem esperar o fechamento das abas. O worker nunca guarda HTML de páginas normais, o que evita servir conteúdo velho ou de outra pessoa.
Registro e página offline
add_action( 'wp_footer', function () {
?>
<script>
if ("serviceWorker" in navigator) {
window.addEventListener("load", function () {
navigator.serviceWorker.register("/sw.js", { scope: "/" });
});
}
</script>
<?php
}, 40 );
Crie uma página /offline/ simples (texto curto: "Você está sem conexão. Tente de novo."). Para um PWA instalável, acrescente um manifesto (manifest.webmanifest) com name, start_url, display e ícones, e um elemento link com rel="manifest" apontando para esse arquivo. O manifesto é opcional se você só quer o cache.
Como testar
Critério de sucesso: estáticos voltam do cache em visitas seguintes, o HTML é revalidado, uma edição do tema aparece sem limpar nada à mão e o modo offline mostra a página combinada.
curl -I https://seusite.com.br/wp-content/themes/seu-tema/style.cssdeve mostrar oCache-Controlde um ano comimmutable; a página HTML mostrano-cache.- No Chrome, Aplicativo, Service Workers: o worker aparece como ativado.
- Marque Offline no painel Rede e recarregue: deve abrir
/offline/. - Edite o CSS do tema e confirme que o
?ver=mudou e a página mostra o novo estilo. - Entre no painel do WordPress e navegue: nenhuma página do admin pode vir do cache do worker.
Erros comuns e como desfazer
| Erro | Efeito | Correção |
|---|---|---|
immutable em arquivo sem versão | mudança invisível por muito tempo | versione com filemtime |
| Cachear HTML no worker | conteúdo velho ou de outro usuário | só rede primeiro para HTML |
Esquecer de trocar VERSAO | cache antigo permanece | incremente a versão ao mudar a lógica |
| Worker preso após remover o arquivo | comportamento estranho | publique um sw.js que se desregistra |
Cache de wp-json | dados velhos | exclua no worker |
Para desfazer um service worker, não basta apagar o arquivo: publique um sw.js mínimo que se desregistra e limpa caches, e remova o registro do rodapé.
self.addEventListener("install", () => self.skipWaiting());
self.addEventListener("activate", (e) => {
e.waitUntil(
caches.keys()
.then((ks) => Promise.all(ks.map((k) => caches.delete(k))))
.then(() => self.registration.unregister())
);
});
Checklist final
- HTTPS ativo.
- Estáticos versionados.
no-cacheno HTML.- Worker sem HTML de páginas.
- Exceções para admin, login, API e carrinho.
- Página offline criada.
- Plano de desregistro testado.
Próximas leituras
O cache combina com preload e fontes e com a limpeza do banco. O curso Core Web Vitals mostra como medir o efeito, e o mini-curso Core Web Vitals no campo ensina a ler o resultado. Plugins originais descritos em camillodantas.com.br/plugins.
Fontes
- Cache-Control header, MDN Web Docs (2026-09-17)
- Using Service Workers, MDN Web Docs (2026-09-25)
- wp_enqueue_style(), WordPress Developer Resources (2026-10-14)
Não sabe por onde começar?
Compare as opções e escolha a trilha pelo seu objetivo.