WordPress White Screen of Death: diagnóstico e resolução para agências

O White Screen of Death — ecrã completamente branco sem mensagem de erro — é um dos problemas mais stressantes para qualquer equipa que gere sites WordPress de clientes. A boa notícia é que tem sempre uma causa identificável. Este guia cobre o diagnóstico sistemático do mais simples ao mais complexo.

O que causa o White Screen of Death

O WSOD ocorre quando o PHP encontra um erro fatal mas o WordPress não está configurado para mostrar erros. O resultado é uma página em branco sem informação. As causas mais comuns por ordem de frequência:

• Plugin ou tema com erro de código (especialmente após update)
• Memória PHP esgotada (memory limit)
• Conflito entre plugins
• Ficheiro functions.php corrompido ou com erro de sintaxe
• Incompatibilidade com versão de PHP do servidor
• Base de dados inacessível ou corrompida

Passo 1: Ativar debug mode para ver o erro real

O primeiro passo é sempre activar o modo de debug do WordPress para revelar o erro que está a causar o WSOD. Adicionar ao wp-config.php:

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);

Com WP_DEBUG_DISPLAY a false, os erros são escritos para /wp-content/debug.log em vez de serem mostrados publicamente. Ler este ficheiro via FTP ou painel de ficheiros do hosting revela a causa raiz na maioria dos casos.

Se o painel de administração também estiver inacessível, ativar temporariamente WP_DEBUG_DISPLAY a true para ver o erro directamente no browser (lembrar de reverter depois).

Passo 2: Desactivar plugins via FTP

Se o erro aponta para um plugin específico, ou se a causa não está clara, desactivar todos os plugins é o próximo passo. Via FTP ou gestor de ficheiros do hosting, renomear a pasta /wp-content/plugins/ para /wp-content/plugins-disabled/.

Se o site recuperar, a causa é um plugin. Reactivar plugins individualmente (renomear de volta para plugins, depois activar um a um no painel) até identificar o culpado.

Via WP-CLI, quando o painel está inacessível mas o SSH funciona:

wp plugin deactivate --all

Passo 3: Mudar para tema padrão

Se desactivar plugins não resolver, o problema pode estar no tema. Via FTP, renomear a pasta do tema activo dentro de /wp-content/themes/. O WordPress vai reverter automaticamente para o tema padrão instalado (Twenty Twenty-Four ou similar).

Se o site recuperar com o tema padrão, o problema está no tema original — frequentemente num ficheiro functions.php com erro de sintaxe introduzido após edição manual.

Passo 4: Aumentar memory limit do PHP

Se o debug.log mostrar Allowed memory size exhausted, o problema é o limite de memória PHP. Adicionar ao wp-config.php:

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

Ou adicionar ao .htaccess:

php_value memory_limit 256M

Se o hosting não permitir aumentar o memory limit desta forma, é necessário contactar o suporte do hosting ou migrar para um plano com mais recursos.

Passo 5: Verificar compatibilidade com versão de PHP

Após um update de PHP no servidor (que pode acontecer sem aviso em alguns hostings partilhados), plugins ou temas antigos podem tornar-se incompatíveis. Verificar a versão de PHP activa no painel do hosting e confrontar com os requisitos dos plugins instalados.

Se o hosting fez um upgrade de PHP recente, reverter temporariamente para a versão anterior enquanto se actualizam ou substituem os plugins incompatíveis.

Passo 6: Verificar integridade dos ficheiros core

Em casos raros, o WSOD pode resultar de ficheiros core do WordPress corrompidos. Via WP-CLI:

wp core verify-checksums

Se detectar ficheiros alterados, reinstalar o core:

wp core download --force

Quando restaurar o backup directamente

Se o diagnóstico demorar mais de 30 minutos sem identificar a causa, e o site tem tráfego ou é um WooCommerce activo, restaurar o backup pré-problema é a decisão certa. Diagnóstico pode ser feito depois num ambiente de staging — o cliente não pode esperar.

Este cenário reforça a importância de ter backups recentes, verificados e de fácil restauro. Para mais detalhes, ver o artigo sobre os melhores plugins de backup WordPress.