# Como corrigir o erro Rocket-Nginx Not Working no WordPress

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.

Erros relacionados

- [Como corrigir o WP Rocket que não gera cache](https://full.services/wp-fixer/corrigir-wp-rocket-nao-gera-cache/)
- [Como corrigir o erro de permissão ao gerar cache no WP Rocket](https://full.services/wp-fixer/corrigir-permissao-cache-wp-rocket/)
- [Como corrigir a exclusão de páginas do cache no WP Rocket](https://full.services/wp-fixer/corrigir-exclusao-cache-wp-rocket/)

## 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

1. 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
```

2. 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
```

3. 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/
```

4. Dentro do bloco server { ... } adicione:

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

5. 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
```

6. 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
```


## Código

```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.

**Fonte:** [Rocket-Nginx (SatelliteWP) — Installation & Configuration](https://github.com/SatelliteWP/rocket-nginx)