# 12 exclusões de cache para não misturar carrinho no Magento

Cache público na categoria e no produto, ESI no minicart, variação por grupo de cliente. E o teste com curl que prova que o carrinho de um visitante não aparece para outro.

> 12 rotas saem do cache público de uma loja Magento: checkout, cart, customer, customer/section/load, wishlist, sales, admin, busca com q, API, callback de pagamento, formulário com form key e newsletter. O resto continua cacheado, com ESI nos blocos dinâmicos.

João Rizzon · 2026-09-30 · Infraestrutura web

---

Cache de página numa loja Magento não é a mesma decisão que num site institucional. No site institucional, ou cacheia ou não cacheia. Na loja, a mesma URL tem partes públicas (nome, foto, descrição do produto) e partes que pertencem a uma pessoa só (minicart, saudação no header, preço do grupo de atacado, form key do checkout). Ligar o cache sem separar essas duas naturezas é o que produz o relato que chega do lojista em tom de pânico: "o cliente viu o carrinho de outra pessoa".

O caminho não é desligar o cache da loja inteira. É montar uma lista de exclusões, marcar os blocos dinâmicos para serem montados fora do cache (hole punching por ESI) e conferir o resultado com dois ou três comandos antes de entregar. Essa lista é a mesma entre lojas de clientes, o que transforma a tarefa em checklist reutilizável.

## Os três sintomas que aparecem primeiro e a causa de cada um

São sempre os mesmos, e cada um tem causa distinta. Reconhecer o sintoma economiza a rodada de tentativa e erro.

**Minicart congelado no header.** O Magento 2 não renderiza o carrinho junto com o HTML da página. Ele carrega o conteúdo privado depois, por uma chamada a `/customer/section/load`. Se essa resposta entrar no cache público, todos os visitantes passam a receber a mesma seção, e o contador do carrinho fica parado, ou pior, mostra o item de outra sessão. A rota de conteúdo privado não pode ser cacheada publicamente em nenhuma circunstância.

**Preço de atacado exibido para visitante.** O preço depende do grupo do cliente. Se a chave do cache não incluir o grupo, a primeira versão gerada é a que fica: se quem aqueceu a página foi um cliente logado no grupo revenda, o visitante anônimo recebe o HTML com o preço de revenda. Isso não é bug do cache, é chave de cache incompleta. O cache público precisa variar por contexto, e grupo de cliente é o contexto mais importante numa loja.

**Checkout em loop ou erro de form key.** O Magento valida o `form_key` de cada requisição que muda estado. Se o HTML cacheado carrega um `form_key` velho e a sessão do visitante tem outro, o POST é rejeitado e o comprador volta para a mesma tela. Também aparece em formulário de contato e em envio de avaliação. Solução: rota de checkout fora do cache público e bloco que imprime o form key resolvido fora do HTML cacheado.

## As 12 rotas que saem do cache público numa loja Magento 2

Esta é a lista que serve de ponto de partida em qualquer loja Magento 2. "Fora do cache público" quer dizer que a resposta não pode ser servida a um segundo visitante. "Privado" quer dizer que pode haver cache, mas atrelado à sessão daquele visitante. "ESI" quer dizer bloco montado separadamente e costurado na página pública.

| Rota ou recurso | Tratamento | Sintoma se cachear como público |
|---|---|---||
| `/checkout/` e subrotas | Fora do cache público | Endereço, frete e form key de outra sessão |
| `/checkout/cart` | Fora do cache público | Carrinho misturado entre visitantes |
| `/customer/section/load` | Fora do cache público | Minicart congelado, contador errado |
| `/customer/` (login, conta, criar) | Fora do cache público | Dado pessoal exposto, login que não "pega" |
| `/wishlist/` | Fora do cache público | Lista de desejos de terceiro |
| `/sales/` (pedido, guest order) | Fora do cache público | Número e status de pedido alheio |
| Rota do admin (frontName próprio) | Fora do cache público | Painel inconsistente, risco de sessão |
| `/catalogsearch/result` com `q=` | Fora do cache público, ou TTL curto | Cache inflado por termo único, resultado errado |
| `/rest/` e `/graphql` | Fora do cache público | Resposta de API servida a outro token |
| Callbacks de pagamento (`/paypal/`, gateway) | Fora do cache público | Retorno de transação perdido ou duplicado |
| `/review/product/post`, `/contact` | Fora do cache público (form key) | Envio rejeitado por form key inválido |
| `/newsletter/` | Fora do cache público | Inscrição atribuída ao e-mail errado |

O que sobra, e é a maior parte do tráfego de uma loja, continua cacheável: home, página de categoria, página de produto, landing de campanha, CMS. Essas são justamente as páginas que o Google rastreia e que o visitante novo abre primeiro.

### Quais cookies precisam entrar na chave do cache

Além da rota, a chave do cache precisa reagir a alguns cookies. Grupo de cliente é obrigatório. Moeda e store view também, se a loja tem mais de uma. Vale revisar `X-Magento-Vary`, `private_content_version`, `section_data_ids` e `mage-cache-sessid` na instalação antes de declarar a configuração pronta. A [documentação do LiteMage Cache](https://docs.litespeedtech.com/lscache/litemage/) descreve como a extensão trata variação de contexto e cache privado; os nomes exatos dos campos mudam entre versões da extensão, então confira na página da versão que você instalou em vez de copiar screenshot de tutorial antigo.

## Hole punching por ESI em vez de desligar o cache da loja

O Magento 2 tem um atalho perigoso no layout XML: `cacheable="false"`. Ele existe para blocos que não podem ser cacheados, e funciona. O problema é o alcance: quando um bloco marcado assim aparece numa página, o Magento desliga o full page cache daquela página inteira. Uma extensão de terceiro que marca um bloco no header com `cacheable="false"` derruba o cache da loja toda, porque o header está em todo lugar. É uma causa frequente de "instalei o cache e o TTFB não mudou", e vale checar antes de suspeitar do servidor.

A alternativa é hole punching. A página é cacheada em público e os pedaços dinâmicos são buracos preenchidos a cada requisição. Em ambiente LiteSpeed, a extensão LiteMage faz isso com ESI: o bloco vira uma inclusão separada, com TTL próprio ou sem cache nenhum, e o resto do HTML permanece público. A documentação oficial da extensão trata desse mecanismo e de como declarar blocos de módulos de terceiro como blocos ESI.

O processo prático numa loja de cliente:

### Encontre os blocos marcados como não cacheáveis

Procure as marcações no layout dos módulos instalados:

```
grep -rn 'cacheable="false"' app/code vendor/*/module-* --include=*.xml
```

Cada resultado é um candidato. Anote o nome do bloco e em que handle de layout ele aparece.

### Classifique cada bloco em três caixas

Bloco que é igual para todo mundo: remova a marcação e deixe no cache público. Bloco que depende do visitante mas aparece em página pública (minicart, saudação, últimos vistos, form key): candidato a ESI. Bloco que só existe em página já excluída (resumo do checkout): não precisa de ESI, a página inteira já está fora do cache público.

### Declare como ESI só os blocos dinâmicos de página pública

Na configuração da extensão, aponte os blocos da segunda caixa. Comece pelo essencial (minicart, header de cliente, form key) e só então avance para os blocos de módulos de terceiro, um por vez. Cada bloco ESI é uma requisição interna extra, então transformar dez blocos em ESI para economizar um miss é troca ruim.

### Limpe o cache e recompile fora do horário de pico

```
bin/magento cache:flush
bin/magento setup:static-content:deploy -f pt_BR
```

Em loja com modo de produção e compilação de dependência, rode também `setup:di:compile` antes do deploy de estático. Fazer isso fora de horário de pico é regra, não preferência.

## Três verificações com curl antes de entregar a loja

Três verificações bastam para dizer que a configuração está correta. Os valores mostrados abaixo são exemplo de saída de comando, escritos para ilustrar o formato, não medição feita por nós.

### O que os cabeçalhos da página de categoria devem mostrar

```
curl -s -D - -o /dev/null \
  -H 'User-Agent: Mozilla/5.0' \
  https://loja.exemplo.com.br/tenis-masculinos.html \
  | grep -i -E 'x-litespeed|cache-control|set-cookie'
```

Exemplo de saída na segunda requisição:

```
x-litespeed-cache: hit
cache-control: public, max-age=86400
```

Se nessa mesma resposta o `cache-control` vier como `no-cache, no-store, must-revalidate`, a página não está sendo guardada em público, e o hit não significa nada útil: o caminho é revisar se alguma exclusão ficou larga demais ou se algum bloco do layout está marcado como não cacheável.

O ponto de atenção é `Set-Cookie` numa resposta marcada como hit público. Cookie de sessão viajando dentro de página compartilhada é o começo do vazamento. Se aparecer, volte para a lista de exclusões antes de qualquer otimização de imagem.

### Como medir TTFB em hit e miss sem derrubar a loja em produção

```
curl -o /dev/null -s -w 'TTFB %{time_starttransfer}s total %{time_total}s\n' \
  https://loja.exemplo.com.br/tenis-masculinos.html
```

Rode três vezes com o cache ligado e três vezes com o cache da loja desativado, sempre na mesma URL, mesma rede e fora de janela de deploy. Desligar o cache de uma loja em produção devolve toda a carga para PHP e MySQL e deixa a loja lenta para clientes reais enquanto durar a medição: faça isso em staging ou numa cópia da loja, ou em janela combinada com o lojista, e religue o cache assim que as três linhas saírem. Se não houver como desligar nada, compare hit e miss forçado na mesma URL: purgue só aquela página, meça a primeira requisição (miss) e a seguinte (hit). Guarde as seis linhas no chamado da agência. É o registro que evita discussão quando o lojista instalar um plugin novo em três meses e disser que "ficou lento de novo".

### O teste de duas sessões que prova que o carrinho não vaza

Este é o teste que responde ao medo real. Duas sessões independentes, dois cookie jars:

```
# sessão A: abre a página do produto e guarda os cookies
curl -s -c jarA.txt -b jarA.txt -o produto.html \
  https://loja.exemplo.com.br/tenis-modelo-x.html

# o form_key viaja num cookie de mesmo nome; extraia do jar
FORM_KEY=$(awk '$6=="form_key"{print $7}' jarA.txt)

# o ID do produto sai do HTML salvo: grep -o 'name="product" value="[0-9]*"' produto.html
curl -s -L -c jarA.txt -b jarA.txt -o /dev/null \
  -d "product=1234" -d "qty=1" -d "form_key=$FORM_KEY" \
  https://loja.exemplo.com.br/checkout/cart/add/product/1234/

# confere que o carrinho da sessão A tem mesmo o item
curl -s -b jarA.txt -c jarA.txt https://loja.exemplo.com.br/checkout/cart \
  | grep -ci 'nome-do-produto-da-sessao-A'

# sessão B: visitante novo, nenhum cookie
curl -s -c jarB.txt https://loja.exemplo.com.br/checkout/cart \
  | grep -ci 'nome-do-produto-da-sessao-A'
```

A penúltima linha precisa devolver pelo menos `1`: se der `0`, o add-to-cart não aconteceu (produto com opção obrigatória, ID errado, form_key expirado) e o teste não prova nada. Para produto configurável ou com opção customizada, o POST exige os campos `super_attribute[...]` ou `options[...]`; nesse caso é mais rápido fazer o add-to-cart no navegador em janela anônima e exportar os cookies para o jar. O resultado esperado da última linha é `0`. Qualquer número acima de zero significa que a rota do carrinho está sendo servida do cache público, e a loja não deve ir ao ar assim.

O mesmo padrão serve para o preço de grupo: faça a sessão A logar num cliente do grupo de atacado, aqueça a página de produto, depois peça a mesma URL com o jar vazio e procure o preço de atacado no HTML. Se ele aparecer para o anônimo, a variação por grupo de cliente não está ativa.

## Checklist de 10 itens para padronizar entre lojas de clientes

O valor da lista é ela ser idêntica em todas as lojas. Copie para o template de entrega da agência.

- Confirmar que o servidor é LiteSpeed e que a extensão de cache está ativa e na versão compatível com a versão do Magento.
- Aplicar as 12 exclusões da tabela, ajustando a rota do admin para o `frontName` daquela loja.
- Ativar variação por grupo de cliente. Se houver múltipla moeda ou store view, variar por elas também.
- Rodar o `grep` de `cacheable="false"` e classificar cada bloco nas três caixas.
- Declarar como ESI o minicart, o header de cliente e o bloco de form key. Um por vez, testando entre cada um.
- Definir TTL público. Categoria e produto suportam TTL longo porque a invalidação vem por evento, não por expiração.
- Conferir que salvar um produto no admin limpa a página daquele produto e as categorias em que ele aparece. A extensão se apoia nas tags de cache do Magento para isso; se a limpeza não acontecer, é sinal de integração incompleta, não de motivo para reduzir o TTL.
- Rodar as três verificações de curl e anexar a saída ao chamado.
- Registrar no runbook da loja: como purgar, quem purga e o que fazer depois de deploy.
- Repetir o teste de isolamento de carrinho toda vez que um módulo novo de checkout, frete ou marketing for instalado.

O item 10 é o que costuma faltar. A configuração de cache não quebra sozinha, quebra no dia em que alguém instala um módulo que marca um bloco do header como não cacheável.

## Quando o cache esconde o problema em vez de resolver

Vale dizer o desconfortável: em parte das lojas lentas, o cache de página melhora o número do visitante novo e esconde um problema que continua ali. Página de categoria com filtro em cima de atributo não indexado, cron de reindex parado, tabela de log de relatório crescendo sem limpeza e extensão que faz consulta por item em loop são coisas que o cache não resolve. Elas reaparecem no checkout, que está justamente fora do cache por construção.

Antes de prometer ganho ao lojista, olhe o log de consulta lenta do MySQL e o estado dos índices (`bin/magento indexer:status`). Se o checkout leva quatro segundos e a categoria leva quatro segundos, o cache vai consertar a categoria e o abandono de carrinho vai continuar igual. Nesse cenário, mudar de plano ou de servidor também não conserta, e dizer isso ao cliente sai mais barato que descobrir depois.

## A frase pronta para explicar ao lojista

O lojista não quer saber de ESI. Ele quer garantia de que ninguém vai comprar no carrinho de outra pessoa. Uma formulação que funciona em reunião:

"O cache guarda só as partes da loja que são iguais para todo mundo: a foto, o nome e a descrição do produto. Carrinho, login, preço do seu grupo de cliente e checkout ficam de fora e são montados na hora, a cada visita. Na prática, a vitrine passa a abrir pronta e a parte que é sua continua individual. Rodamos um teste em duas sessões separadas para comprovar que o carrinho de um visitante não aparece para outro, e a saída do teste está anexada."

Duas frases sobre o que entra, uma sobre o que fica de fora, uma sobre a prova. Anexar a saída do curl do teste de isolamento transforma promessa em evidência e encerra o assunto.

## Referência

- [LiteMage Cache, documentação oficial LiteSpeed](https://docs.litespeedtech.com/lscache/litemage/) (consultado em 29/09/2026): mecanismo de ESI, cache privado e variação de contexto da extensão.

As rotas listadas na tabela correspondem à estrutura padrão do Magento 2. Confira o `frontName` do admin e as rotas dos módulos de pagamento instalados em cada loja antes de aplicar a lista, porque essas duas variam por instalação.

