Mudei o site e nada mudou: o cache que servia o CSS velho

Todo mundo que tem um site já passou por isso: você muda alguma coisa, publica, e nada muda. No meu caso, era uma cor. Clareei o cinza dos textos secundários do Curtly para melhorar a acessibilidade, o deploy terminou sem erro, e o site no ar continuava com o cinza antigo. Não era o meu navegador. Não era a CDN. Era um cache de build reaproveitando uma versão velha do CSS.

Conto a investigação inteira porque ela serve para qualquer pessoa que já gritou "mas eu mudei isso!" para a tela.

#O sintoma

A mudança era uma linha no arquivo de estilos: o cinza passou de um tom com contraste de cerca de 4:1 sobre o fundo para um tom mais claro, acima de 4,5:1, o mínimo recomendado. Depois do deploy, o teste de acessibilidade continuava reclamando exatamente da cor antiga, #717171.

O curioso: o mesmo aconteceu no meu computador. Eu gerava a versão de produção do site, abria, e lá estava o cinza velho.

#A investigação, camada por camada

Quando uma mudança não aparece, existem três suspeitos, sempre nessa ordem:

#1. O cache do navegador

O mais comum. O navegador guardou os arquivos da visita anterior. Teste: abrir em janela anônima. No meu caso, não resolveu, e nem poderia: o teste automático já roda sem cache.

#2. O cache da CDN

Se o site fica atrás de uma CDN, ela pode estar entregando a versão antiga guardada. Teste: comparar o que a CDN entrega com o que o servidor gera. O site do Curtly não tem a Cloudflare na frente, e a rede da própria Vercel troca o conteúdo guardado a cada deploy novo, então descartei.

#3. O cache do build

O suspeito que quase ninguém considera. Ferramentas modernas guardam o resultado de builds anteriores para os próximos serem mais rápidos. Se esse cache não perceber uma mudança, o build "novo" sai com pedaços velhos.

O teste decisivo foi olhar o que estava sendo entregue de fato. Baixei a página e procurei a variável de cor no CSS:

curl -s https://www.curtly.pro/ | grep -o "muted-foreground:[^;]*"

Resultado: #717171, o valor antigo. O arquivo no repositório tinha o valor novo. Ou seja, o código estava certo e o site no ar estava errado.

No meu computador, apaguei a pasta de build (.next) e gerei de novo. A cor nova apareceu: #8f8f8f. Estava confirmado: era o cache de build.

#A causa

O Curtly usa Next.js 16, que vem com o cache de sistema de arquivos do Turbopack ligado por padrão também no build. A documentação explica que ele "guarda o trabalho do Turbopack para next build em .next/cache/turbopack", para que os builds seguintes "comecem aquecidos". E a Vercel restaura essa pasta entre um deploy e outro.

Na maior parte do tempo, isso é ótimo: builds mais rápidos. Mas no meu caso, depois de uma mudança no arquivo de estilos, o build reaproveitou o CSS antigo. Não sei dizer se é um defeito do framework ou alguma combinação específica do projeto. O que sei é o que observei e como resolvi.

#A solução

A própria documentação mostra como desligar esse cache só no build:

// next.config.mjs
const nextConfig = {
  experimental: {
    turbopackFileSystemCacheForBuild: false,
  },
}

O custo é um deploy um pouco mais lento, porque cada build começa do zero. O benefício é a garantia de que o que vai para o ar é exatamente o código enviado. Para um site em que um deploy por dia é muito, a troca vale a pena.

Depois do deploy, conferi de novo com o curl: #8f8f8f. A acessibilidade da página foi para 100.

#O roteiro para quando "mudei e não mudou"

1. Janela anônima. Resolve o cache do navegador.
2. Confira o que o site entrega. "Ver código-fonte" no navegador, ou curl no terminal, procurando o texto ou o valor que você mudou.
3. Se tiver CDN, compare com a origem. Ou limpe o cache da CDN pelo painel dela.
4. Gere o build do zero. Apague a pasta de build (.next no Next.js) ou, na Vercel, refaça o deploy sem usar o cache de build.
5. Só então mexa no código de novo. Muita gente reescreve um código que já estava certo por causa de um cache.

#Por que isso importa para SEO e acessibilidade

Um site que você acha que corrigiu, mas continua quebrado no ar, é o pior dos mundos: você para de procurar o problema, e o Google e os seus visitantes continuam vendo a versão com defeito. Desde esse episódio, criei um hábito: depois de cada deploy importante, confiro o site de fora, baixando a página real e procurando a mudança, em vez de confiar só no "deploy concluído".

Fontes: Next.js: turbopackFileSystemCache, web.dev: contraste de cor e acessibilidade.