receita

Receita: cache e PWA

Cabeçalhos de cache para arquivos estáticos e um service worker conservador com página offline.

resposta curtaCache bom tem duas camadas. Na camada HTTP, arquivos versionados recebem Cache-Control com max-age longo e immutable, e o HTML fica com no-cache para ser revalidado sempre. Na camada do navegador, um service worker conservador usa a rede primeiro e guarda só os estáticos e uma página offline. Nunca armazene áreas logadas, carrinho ou formulários.
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;
  • immutable em 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

  1. 01Defina a política: estáticos com cache longo, HTML sempre revalidado.
  2. 02Aplique os cabeçalhos no servidor.
  3. 03Crie o service worker com rede primeiro para páginas e cache para estáticos.
  4. 04Registre o worker e crie a página offline.
  5. 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.

  1. curl -I https://seusite.com.br/wp-content/themes/seu-tema/style.css deve mostrar o Cache-Control de um ano com immutable; a página HTML mostra no-cache.
  2. No Chrome, Aplicativo, Service Workers: o worker aparece como ativado.
  3. Marque Offline no painel Rede e recarregue: deve abrir /offline/.
  4. Edite o CSS do tema e confirme que o ?ver= mudou e a página mostra o novo estilo.
  5. Entre no painel do WordPress e navegue: nenhuma página do admin pode vir do cache do worker.

Erros comuns e como desfazer

ErroEfeitoCorreção
immutable em arquivo sem versãomudança invisível por muito tempoversione com filemtime
Cachear HTML no workerconteúdo velho ou de outro usuáriosó rede primeiro para HTML
Esquecer de trocar VERSAOcache antigo permaneceincremente a versão ao mudar a lógica
Worker preso após remover o arquivocomportamento estranhopublique um sw.js que se desregistra
Cache de wp-jsondados velhosexclua 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-cache no 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

  1. Cache-Control header, MDN Web Docs (2026-09-17)
  2. Using Service Workers, MDN Web Docs (2026-09-25)
  3. 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.