Configuração do projeto

Cache na CDN

Todo projeto HTTP público passa pela CDN incluída na Zenifra. A CDN guarda cópias de arquivos estáticos perto do visitante. Assim, esses arquivos chegam mais rápido e a instância fica livre para responder ao resto. Quem decide por quanto tempo cada arquivo fica em cache é a sua aplicação, pelo cabeçalho Cache-Control.

O que fica em cache

RespostaFica em cache na CDN?
Arquivo estático (lista abaixo) com status 200Sim, pelo tempo definido pela aplicação ou pelo padrão
HTML, API e qualquer caminho sem extensão (/, /produtos, /api/pedidos)Não. Sempre vai até a aplicação, mesmo com Cache-Control: public
Status 404Não. Um arquivo que ainda não existe durante um deploy não fica preso
Resposta com Cache-Control: no-store ou privateNão
Resposta que envia Set-CookieNão
Requisições POST, PUT, PATCH e DELETENão

Extensões tratadas como arquivo estático: 7z, avi, avif, apk, bin, bmp, bz2, class, css, csv, doc, docx, dmg, ejs, eot, eps, exe, flac, gif, gz, ico, iso, jar, jpg, jpeg, js, mid, midi, mkv, mp3, mp4, ogg, otf, pdf, pict, pls, png, ppt, pptx, ps, rar, svg, svgz, swf, tar, tif, tiff, ttf, webm, webp, woff, woff2, xls, xlsx, zip, zst.

A URL completa, incluindo a query string, identifica a cópia. /app.js?v=1 e /app.js?v=2 são guardados separadamente.

Atenção: a CDN não diferencia usuários. Uma requisição com Authorization ou cookie de sessão recebe a mesma cópia em cache de um arquivo estático. Não sirva conteúdo privado em caminhos com essas extensões; se precisar, responda com Cache-Control: private ou no-store.

Tempo padrão

Quando um arquivo estático não traz Cache-Control, a CDN o guarda por 2 horas. Nesse caso, a Zenifra não envia Cache-Control ao navegador, que segue o comportamento padrão dele.

Como mudar o tempo de cache

Envie o cabeçalho Cache-Control pela aplicação (no framework, middleware ou servidor web). A CDN respeita o valor da aplicação:

Cabeçalho enviado pela aplicaçãoNa CDNNo navegador
Cache-Control: public, max-age=31536000, immutable1 ano1 ano
Cache-Control: public, max-age=6060 segundos60 segundos
Cache-Control: public, max-age=3600, s-maxage=6060 segundos (s-maxage vale para a CDN)1 hora
Cache-Control: public, max-age=3600 + CDN-Cache-Control: max-age=6060 segundos (o CDN-Cache-Control não chega ao navegador)1 hora
Cache-Control: public, max-age=60, stale-while-revalidate=30060 segundos; depois disso, entrega a cópia antiga na hora e busca a nova em segundo plano60 segundos
Cache-Control: no-cache ou max-age=0Guarda, mas consulta a aplicação a cada requisiçãoRevalida a cada uso
Cache-Control: no-store ou privateNão guardano-store: não guarda; private: só o navegador guarda

Exemplo em Express:

// Arquivos com hash no nome: cache longo
app.use('/assets', express.static('dist/assets', { maxAge: '1y', immutable: true }))

// Arquivo que muda sem trocar de nome: 5 minutos na CDN e no navegador
app.get('/widget.js', (req, res) => {
  res.set('Cache-Control', 'public, max-age=300')
  res.sendFile('widget.js', { root: 'public' })
})

Exemplo em Nginx:

location /assets/ {
    add_header Cache-Control "public, max-age=31536000, immutable";
}

Diferença de latência

Uma resposta em cache sai do ponto da CDN mais próximo do visitante. Sem cache, a requisição precisa ir até a aplicação, e o tempo cresce com a distância. Medição do tempo até o primeiro byte de um mesmo projeto, em novembro de 2026:

Visitante emEm cacheSem cache
São Paulo~26 ms~51 ms
Porto Alegre~34 ms~68 ms
Fortaleza~8 ms~74 ms
Miami (EUA)~40 ms~510 ms
Frankfurt (Alemanha)~48 ms~900 ms

Por isso vale usar cache longo nos arquivos estáticos que têm nome versionado.

Publicar uma versão nova e invalidar o cache

Um deploy novo, um reinício ou a troca de imagem não limpam o cache da CDN. Até o tempo de cache acabar, os visitantes podem receber a versão anterior de um arquivo que manteve o mesmo nome. Hoje não há uma ação no console ou na API para limpar o cache. Use uma destas formas:

  • Nome com hash (recomendado): ferramentas como Vite, Next.js, webpack e Angular geram nomes como app.3f9a2c.js a cada build. Cada versão tem uma URL nova e pode usar cache longo (max-age=31536000, immutable). O HTML, que nunca fica em cache na CDN, aponta sempre para os nomes novos.
  • Versão na URL: troque /app.js?v=1 por /app.js?v=2. A CDN trata como outro arquivo.
  • Tempo curto: para arquivos que mudam sem trocar de nome, use um max-age curto ou no-cache. A versão nova aparece em, no máximo, esse tempo.

Como conferir

O cabeçalho Age mostra há quantos segundos a cópia está em cache (ele só aparece quando a resposta veio do cache):

curl -sI https://seu-projeto.clients.zenifra.com/assets/app.js | grep -i -E "^(age|cache-control):"

FAQ

Posso guardar HTML ou respostas de API na CDN?

Não. Caminhos sem extensão de arquivo estático sempre vão até a aplicação. Para acelerar páginas e APIs, use cache na própria aplicação, como o Cache Valkey gerenciado.

Mudei um arquivo e o visitante ainda vê o antigo. O que faço?

Troque a URL do arquivo (nome com hash ou ?v=) e publique o HTML que aponta para ela. A cópia antiga sai da CDN quando o tempo de cache acabar.

O cache da CDN muda o que a minha aplicação recebe?

Só reduz o número de requisições de arquivos estáticos que chegam à instância. O IP real do visitante e os cabeçalhos das requisições que chegam continuam os mesmos.

Última atualização em

Nessa página