Corrigindo a Tela Branca da Morte no WordPress

A tela branca da morte do WordPress é um erro fatal do PHP com a exibição de erros desativada: o código travou antes de produzir qualquer HTML, e o WordPress oculta a mensagem de erro para que ela não vaze caminhos de arquivos e detalhes do servidor para os visitantes.

Você atualiza um plugin, recarrega o site e recebe uma página em branco no front end, muitas vezes no wp-admin também. Nenhum erro, nenhum stack trace, nada em que clicar. A tentação é começar a desativar coisas aleatoriamente, mas a mensagem já existe; ela apenas não está sendo mostrada para você. Cada passo abaixo funciona via SFTP ou pelo gerenciador de arquivos da hospedagem, e há um caminho pelo banco de dados para hospedagens que oferecem phpMyAdmin, mas não acesso a arquivos.

O Que É a Tela Branca da Morte do WordPress?

Uma tela branca significa que o PHP encontrou um erro fatal antes de conseguir renderizar a página, e o WordPress deliberadamente suprime o texto do erro em sites de produção porque ele pode expor caminhos, versões e outros detalhes internos. Os arquivos e o banco de dados do site estão intactos; apenas um componente derrubou a requisição.

Antes de mexer em qualquer coisa, verifique a caixa de entrada do e-mail administrativo. Desde a versão 5.2, o WordPress envia um e-mail ao administrador quando ocorre um erro fatal, nomeando o plugin ou tema que falhou e incluindo um link que ativa o Modo de Recuperação, um estado em que o componente quebrado é pausado para que você possa acessar o painel e desativá-lo. Esse link carrega uma chave secreta; digitar a URL do Modo de Recuperação manualmente não concede acesso. Se o e-mail nunca chegar (filtros de spam o engolem, e o e-mail só é enviado quando o erro atinge um endpoint protegido, como wp-login.php ou a área administrativa, não uma página do front end ou uma tarefa cron), continue abaixo.

Ative o Registro em Log, Não a Exibição

Abra o wp-config.php via SFTP ou pelo gerenciador de arquivos da sua hospedagem e adicione estas linhas acima de /* That's all, stop editing! */:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

Recarregue a página quebrada e depois abra o log, normalmente em wp-content/debug.log. Conforme a documentação de depuração do WordPress, WP_DEBUG_LOG não tem efeito a menos que WP_DEBUG seja true, e WP_DEBUG_DISPLAY tem valor padrão true, razão pela qual o trecho de código o define explicitamente como false. Nunca imprima erros na página em um site em produção: todo visitante veria caminhos do servidor e detalhes do código. Remova todas as quatro linhas depois que o site estiver corrigido.

Leia o Erro: O Caminho Identifica o Culpado

O log fornece um arquivo e um número de linha, e o diretório nesse caminho indica qual componente falhou. Uma entrada realista se parece com isto:

PHP Fatal error: Uncaught Error: Call to undefined function acme_slider_init() in /home/example/public_html/wp-content/plugins/acme-slider/includes/display.php:87

O caminho está sob wp-content/plugins/acme-slider/, então o plugin Acme Slider é a causa, e renomear essa única pasta corrige o site imediatamente. Como regra geral:

Se o log indicar um erro de memória, leia a próxima seção. Somente se o log estiver vazio você deve recorrer aos passos de bisseção.

Como Corrigir um Erro de Esgotamento de Memória no WordPress?

Um erro começando com Allowed memory size of X bytes exhausted significa que o PHP atingiu seu teto de memória no meio da requisição. Aumente o limite do WordPress no wp-config.php:

define( 'WP_MEMORY_LIMIT', '256M' );

O WordPress define WP_MEMORY_LIMIT como 40M por padrão em sites individuais e 64M em multisite, e apenas aumenta o limite do PHP, nunca o reduz. A constante funciona apenas até o teto que sua hospedagem impõe no nível do servidor; se 256M não mudar nada, o limite está no plano de hospedagem, não na configuração, e você precisará que a hospedagem o aumente.

Como Desativar um Plugin Problemático Sem o wp-admin?

Se o log nomear um plugin, renomeie apenas a pasta daquele plugin dentro de wp-content/plugins/. Se o log estiver vazio, faça a bisseção: renomeie wp-content/plugins para plugins.hold, carregue /wp-admin/plugins.php para que o WordPress marque os plugins ausentes como desativados, renomeie a pasta de volta e então reative os plugins um por um, recarregando o site após cada um, até que ele quebre. Reativar todos os plugins manualmente é o preço desse caminho, mas quaisquer configurações que cada um armazenou permanecem intactas.

Sem acesso a arquivos, mas com phpMyAdmin disponível? Abra a tabela wp_options (seu prefixo pode não ser wp_), encontre a linha em que option_name é active_plugins e copie ou exporte o option_value atual para um local seguro. Depois substitua o valor pelo array vazio serializado a:0:{}, que desativa todos os plugins de uma vez. Restaure o valor salvo mais tarde, se precisar da lista original.

Como Desabilitar um Tema Quebrado?

Se o log apontar para wp-content/themes/, renomeie apenas a pasta do tema ativo, por exemplo mytheme para mytheme.hold. O WordPress recorre a um tema padrão incluído, se houver algum instalado; se não houver, instale um primeiro pelo gerenciador de arquivos. O culpado habitual é o functions.php, e o log já lhe informou a linha exata, muitas vezes uma edição recente com um erro de sintaxe. Corrija essa linha e renomeie a pasta de volta.

Ainda em Branco? Caches, Permissões e Versão do PHP

Antes de confiar em qualquer resultado, limpe todos os caches: o cache de página do plugin, qualquer cache de servidor e o do seu navegador. Uma página em branco em cache pode fazer um site corrigido parecer quebrado, e uma página boa em cache pode esconder um erro ativo. Depois verifique as permissões de arquivo, tipicamente 755 para diretórios e 644 para arquivos em hospedagem compartilhada, e confirme sua versão do PHP: a base recomendada pelo WordPress é 8.3 ou superior. Um site rodando 7.4 ainda vai carregar, mas esse branch parou de receber correções de segurança anos atrás.

Três casos ficam fora do escopo deste artigo: restauração a partir de um backup (a ferramenta de backup da sua hospedagem, observando que você perde tudo desde o snapshot), arquivos do core corrompidos (recopie um download novo do WordPress sobre tudo, exceto wp-content e wp-config.php) e malware (siga o processo de recuperação de sites invadidos da sua hospedagem).

Conclusão

Uma página em branco do WordPress é uma mensagem de erro suprimida, não um mistério, e a correção mais rápida é sempre ler essa mensagem em vez de tentar adivinhar. Adicione as quatro linhas de depuração ao wp-config.php agora, recarregue uma vez e deixe o caminho no wp-content/debug.log lhe dizer exatamente qual pasta renomear.

Perguntas Frequentes

Qual é a diferença entre a tela branca da morte e a mensagem 'Houve um erro crítico neste site'?

Desde o WordPress 5.2, um manipulador de erros fatais embutido captura a maioria dos erros fatais do PHP e exibe a mensagem de erro crítico em vez de uma página em branco. Uma tela totalmente branca significa que o PHP morreu antes de esse manipulador poder ser executado, geralmente por esgotamento de memória ou por um erro muito no início do carregamento, como dentro do wp-config.php. Ambos decorrem de erros fatais do PHP, e os passos de depuração são idênticos.

Por que o wp-content/debug.log está vazio mesmo com o WP_DEBUG habilitado?

As causas usuais são um erro que ocorre antes de as constantes de depuração entrarem em vigor, como um erro de sintaxe dentro do próprio wp-config.php, ou um diretório wp-content no qual o servidor web não consegue escrever, o que impede o WordPress de criar o arquivo. Confirme que as constantes estão acima do comentário de 'stop editing' e depois solicite à sua hospedagem o log de erros do PHP no nível do servidor, que registra erros fatais independentemente das configurações do WordPress.

Por que a tela branca aparece em algumas páginas, mas não em outras?

O erro fatal está em código que só é executado nessas requisições. Uma falha em um arquivo de template do tema deixa o front end em branco enquanto o wp-admin continua funcionando, porque o admin não renderiza templates do front end. Uma falha em código de plugin exclusivo do admin faz o oposto. Habilite o registro de depuração, carregue uma página quebrada, e o caminho do arquivo no erro registrado identifica o componente que está falhando.

É seguro deixar WP_DEBUG e WP_DEBUG_LOG habilitados após corrigir o site?

Não. O log tem como padrão wp-content/debug.log, um caminho previsível e acessível pela web que muitas hospedagens não bloqueiam, então qualquer pessoa que solicitar essa URL pode ler caminhos de arquivos, detalhes de erros e detalhes internos de plugins, e o arquivo cresce sem rotação. Remova as linhas de depuração do wp-config.php quando o site voltar a funcionar, ou defina WP_DEBUG_LOG para um caminho de arquivo personalizado fora da raiz pública da web.