Rocket-Nginx Not Working: como corrigir o cache do Nginx

Tipo Performance & Velocidade

Nome do erro Rocket-Nginx nao esta servindo o cache EN: Rocket-Nginx Not Working

Severidade Atenção

Descrição O erro Rocket-Nginx not working acontece quando o Nginx deixa de servir as páginas em cache do WP Rocket direto do disco, geralmente porque o include do default.conf não esta no server block, o rocket-parser.php não foi rodado após editar o .ini, ou alguma condicao de bypass (query string, cookie, requisicao POST) impede o HIT.

O que é Rocket-Nginx Not Working?

O Rocket-Nginx not working e a falha em que o complemento Rocket-Nginx para de entregar o HTML em cache do WP Rocket diretamente pelo servidor web. O Rocket-Nginx e uma configuração de Nginx, mantida pela SatelliteWP, que serve o arquivo estático gerado pelo WP Rocket antes mesmo do PHP ser carregado. Quando funciona, o Nginx responde com o cabeçalho X-Rocket-Nginx-Serving-Static igual a HIT e a página e devolvida sem passar pelo WordPress. Quando para de funcionar, toda requisicao volta a acionar o PHP e o ganho de velocidade do cache servido pelo servidor desaparece.

Na prática o sintoma e o cabeçalho X-Rocket-Nginx-Serving-Static respondendo MISS ou BYPASS em páginas que deveriam estar em cache, ou a ausencia total dos cabeçalhos X-Rocket-Nginx. Segundo a documentação oficial do projeto, o fluxo correto exige renomear o rocket-nginx.ini.disabled para rocket-nginx.ini, rodar o rocket-parser.php para gerar o default.conf, incluir esse arquivo no server block do Nginx e recarregar o serviço. Pular qualquer uma dessas etapas, ou esquecer de regenerar a configuração após editar o .ini, derruba a entrega do cache pelo Nginx.

Como identificar

O cabeçalho de resposta ‘X-Rocket-Nginx-Serving-Static: MISS’ ou ‘X-Rocket-Nginx-Serving-Static: BYPASS’ aparece em páginas que já deveriam estar em cache.
Nenhum cabeçalho ‘X-Rocket-Nginx-…’ aparece na resposta, indicando que o include do default.conf não esta ativo no server block.
O comando ‘nginx -t’ retorna erro de sintaxe apontando para a linha do include do Rocket-Nginx, e o reload falha.
O cabeçalho ‘X-Rocket-Nginx-Reason’ traz um motivo como cookie, query string ou método POST, mostrando que a requisicao caiu numa regra de bypass.
O site continua lento mesmo com o cache do WP Rocket gerado, porque toda requisicao volta a carregar o PHP em vez de servir o arquivo estático.

Antes de começar: Editar a configuração do Nginx em producao pode derrubar o site se a sintaxe ficar invalida. Faça um backup do arquivo de configuração do servidor antes de alterar, rode sempre o nginx -t antes do reload, e de preferencia teste a mudanca primeiro em um ambiente de staging para poder reverter sem afetar os visitantes.

Como prevenir

Versione o rocket-nginx.ini junto com a configuração do servidor e rode o rocket-parser.php no deploy, para que o default.conf nunca fique defasado em relacao ao .ini.
Após qualquer mudanca no Nginx, padronize a sequencia nginx -t seguido de service nginx reload, evitando aplicar configuração com sintaxe invalida.
Monitore o cabeçalho X-Rocket-Nginx-Serving-Static em páginas chave depois de cada deploy ou atualização do WP Rocket, para detectar uma queda de HIT para MISS logo que acontece.
Documente o caminho real do cache do WP Rocket (wp-content/cache/wp-rocket) e mantenha ele igual ao configurado no rocket-nginx.ini, para não gerar MISS por divergencia de diretório.

Causa

O arquivo default.conf gerado pelo rocket-parser.php não foi incluido no server block do Nginx com a diretiva 'include rocket-nginx/conf.d/default.conf;', entao o Nginx nunca tenta servir o cache antes do PHP.
O rocket-nginx.ini ainda esta como rocket-nginx.ini.disabled, ou foi editado mas o rocket-parser.php não foi executado de novo, deixando o default.conf desatualizado ou inexistente.
A requisicao casa com uma condicao de bypass documentada pelo Rocket-Nginx (método POST, query string na URL, presenca do arquivo .maintenance ou um cookie de exclusão), fazendo o cabeçalho X-Rocket-Nginx-Serving-Static responder BYPASS.
O caminho de cache configurado no rocket-nginx.ini não bate com o diretório real onde o WP Rocket grava o cache (wp-content/cache/wp-rocket), entao o Nginx procura o arquivo estático, não encontra e responde MISS.
O nginx -t passou mas o serviço não foi recarregado com 'service nginx reload' após a mudanca, entao a configuração nova com o include do Rocket-Nginx ainda não esta em vigor no processo do Nginx.

Como resolver

Confirme o cabeçalho que o Nginx esta devolvendo: Antes de mexer em qualquer arquivo, descubra em que estado o Rocket-Nginx esta. Inspecione os cabeçalhos de resposta de uma página pública que deveria estar em cache e leia o valor de X-Rocket-Nginx-Serving-Static. HIT significa que esta servindo do disco, MISS que não achou o arquivo, BYPASS que uma regra excluiu a página, e a ausencia total do cabeçalho indica que o include nem esta ativo.
```
curl -I https://seusite.com.br/
Procure na resposta a linha X-Rocket-Nginx-Serving-Static
Leia também X-Rocket-Nginx-Reason se o valor for MISS ou BYPASS
```
Gere a configuração com o rocket-parser.php: Na pasta do Rocket-Nginx, garanta que o arquivo de configuração esteja ativo e regenere o default.conf. O rocket-nginx.ini.disabled precisa ser copiado para rocket-nginx.ini, e o parser precisa rodar para transformar o .ini no arquivo .conf que o Nginx vai incluir. Sempre que editar o .ini, rode o parser de novo.
```
cp rocket-nginx.ini.disabled rocket-nginx.ini
php rocket-parser.php
Confirme que o arquivo rocket-nginx/conf.d/default.conf foi criado
```
Inclua o default.conf no server block do Nginx: Edite o arquivo de configuração do site no Nginx e adicione a diretiva include dentro do bloco server, apontando para o default.conf gerado pelo parser. Sem esse include, o Nginx nunca executa as regras do Rocket-Nginx e nenhum cabeçalho X-Rocket-Nginx aparece na resposta.
```
Abra o arquivo do site em /etc/nginx/sites-available/
```

Dentro do bloco server { ... } adicione:

include rocket-nginx/conf.d/default.conf;

Teste a sintaxe e recarregue o Nginx: Valide a configuração com nginx -t antes de aplicar. Se o teste apontar erro na linha do include, corrija o caminho do default.conf. Com o teste OK, recarregue o serviço para que a configuração nova entre em vigor sem derrubar as conexoes ativas.
```
nginx -t
service nginx reload
```
Valide o HIT e investigue bypass residual: Repita a inspecao do passo 1 numa página em cache. O esperado agora e X-Rocket-Nginx-Serving-Static igual a HIT. Se ainda vier MISS, confira se o caminho de cache no rocket-nginx.ini bate com wp-content/cache/wp-rocket. Se vier BYPASS, leia o X-Rocket-Nginx-Reason: ele aponta a regra que excluiu a página, como query string, cookie ou método POST.
```
curl -I https://seusite.com.br/
Confirme X-Rocket-Nginx-Serving-Static: HIT
Se MISS ou BYPASS, leia X-Rocket-Nginx-Reason e ajuste o caminho de cache ou a regra no rocket-nginx.ini
```

NGINX

# /etc/nginx/sites-available/seusite.conf
server {
    listen 443 ssl;
    server_name seusite.com.br;
    root /var/www/seusite/htdocs;

    # Inclui as regras geradas pelo rocket-parser.php.
    # Sem este include o Nginx nunca serve o cache do WP Rocket.
    include rocket-nginx/conf.d/default.conf;

    location / {
        try_files $uri $uri/ /index.php?$args;
    }

    location ~ .php$ {
        include fastcgi_params;
        fastcgi_pass unix:/run/php/php-fpm.sock;
    }
}

Perguntas frequentes

O que significa X-Rocket-Nginx-Serving-Static igual a MISS

MISS significa que o Nginx tentou servir a página em cache pelo disco mas não encontrou o arquivo estático correspondente. Em geral o cache ainda não foi gerado para aquela URL ou o caminho de cache configurado no rocket-nginx.ini não bate com a pasta wp-content/cache/wp-rocket onde o WP Rocket grava os arquivos.

Por que nenhum cabeçalho X-Rocket-Nginx aparece na resposta

A ausencia total dos cabeçalhos X-Rocket-Nginx indica que o include do default.conf não esta ativo no server block do Nginx. Adicione a diretiva include rocket-nginx/conf.d/default.conf dentro do bloco server, valide com nginx -t e recarregue o serviço para que as regras passem a rodar.

Qual a diferenca entre MISS e BYPASS no Rocket-Nginx

MISS quer dizer que o arquivo de cache não foi encontrado para servir. BYPASS quer dizer que a requisicao casou com uma regra de exclusão, como método POST, query string na URL, arquivo .maintenance presente ou um cookie específico. O cabeçalho X-Rocket-Nginx-Reason indica qual condicao causou o BYPASS.

Preciso rodar o rocket-parser.php toda vez que mudo a configuração

Sim. O rocket-parser.php le o rocket-nginx.ini e gera o default.conf que o Nginx inclui. Se você editar o .ini e não rodar o parser de novo, o Nginx continua usando a configuração antiga e a mudanca não tem efeito. Rode o parser após cada alteração no .ini.

Como sei que o Rocket-Nginx voltou a funcionar

Inspecione os cabeçalhos de uma página em cache com curl -I na URL do site. Se X-Rocket-Nginx-Serving-Static responder HIT, o Nginx esta servindo o HTML do disco antes do PHP, que e o comportamento correto. HIT confirma que o include, o parser e o caminho de cache estão todos certos.

O Rocket-Nginx funciona em servidor Apache

Não. O Rocket-Nginx e uma configuração específica para o servidor web Nginx, que serve o arquivo estático antes do PHP por meio de regras no server block. Em Apache o WP Rocket usa as regras de cache no .htaccess, e o complemento Rocket-Nginx não se aplica.

Por que a página cai em BYPASS por causa de query string

Por padrão o Rocket-Nginx não serve do disco URLs com argumentos de query string, porque elas podem gerar conteúdo diferente a cada parametro. Quando isso acontece, o X-Rocket-Nginx-Reason aponta a query string como motivo. Ajuste as regras no rocket-nginx.ini e rode o parser se quiser tratar parametros especificos.

O include do Rocket-Nginx pode quebrar o site

Pode, se a sintaxe ou o caminho do default.conf estiverem errados, porque o Nginx falha ao carregar a configuração. Por isso rode sempre nginx -t antes de aplicar e mantenha um backup do arquivo de configuração do servidor para reverter caso o teste ou o reload acuse erro.

Grave

Como corrigir o cache que não funciona no WP-Optimize

O cache do WP-Optimize não funciona quando o plugin não consegue gravar a página estática na pasta wp-content/wpo-cache, geralmente por cache desativado, permissão de escrita negada ou conflito com outro plugin de cache ativo.

Grave

Como corrigir o erro de JavaScript ao combinar arquivos no WP Rocket

A opção Combine JavaScript Files do WP Rocket junta todos os scripts em um único arquivo; quando dois scripts dependem de ordem ou de uma variavel global, a juncao gera erro de JavaScript e quebra menu, carrossel, slider ou formulário. A correção e excluir o arquivo conflitante do combine.

Grave

Como corrigir o cache do WP Rocket em páginas dinâmicas do WooCommerce

O cache do WP Rocket no WooCommerce mostra carrinho, total ou estoque desatualizados quando uma página dinâmica é servida como HTML estático. O WP Rocket exclui carrinho, checkout e minha conta automaticamente, mas páginas customizadas ou cookies próprios precisam de exclusão manual.

Atenção

Como corrigir o erro de Critical CSS não gerado no WP Rocket

O erro Critical CSS not generated no WP Rocket ocorre quando a API do plugin não consegue acessar a página para gerar o CSS crítico, retornando mensagens como Invalid response code, cURL error 28 ou Timeout. A causa quase sempre e bloqueio de IP por firewall, Cloudflare Bot Fight Mode ou WP-cron parado.

Grave

Como corrigir a integração de CDN do WP Rocket que não funciona

WP Rocket CDN não funciona é quando a opção Content Delivery Network está ativa mas o plugin não reescreve as URLs dos arquivos estáticos, então imagens, CSS e JS continuam saindo pelo domínio do site. No código-fonte, os assets ainda apontam para o domínio principal, e não para o CNAME informado.

Atenção

Como corrigir a exclusão de páginas do cache no WP Rocket no WordPress

A exclusão de uma página do cache no WP Rocket não funciona quando o padrão de URL no campo Never Cache URL(s) está mal formatado, quando um cache de servidor ou CDN fica acima do plugin, ou quando o Preload recacheia a página logo após a limpeza.

Setores

Extensões

Integrações

Como corrigir o erro Rocket-Nginx Not Working no WordPress

O que é Rocket-Nginx Not Working?

Como identificar

Como prevenir

Causa

Como resolver

Perguntas frequentes

Itens relacionados

Como corrigir o cache que não funciona no WP-Optimize

Como corrigir o erro de JavaScript ao combinar arquivos no WP Rocket

Como corrigir o cache do WP Rocket em páginas dinâmicas do WooCommerce

Como corrigir o erro de Critical CSS não gerado no WP Rocket

Como corrigir a integração de CDN do WP Rocket que não funciona

Como corrigir a exclusão de páginas do cache no WP Rocket no WordPress

Setores

Extensões

Integrações

Extensões

Hero Sections

Seções de CTA

Login

Blog

Cabeçalhos

Seções de FAQ

Cadastro

Blog individual

Rodapés

Seções de contato

Seções de preços

Faixas

Portfólio

Seções de equipe

Números

Logotipos