Como Debugar WordPress com WP_DEBUG: Guia Completo

Seu site WordPress está se comportando de forma estranha. Um plugin não funciona, uma página exibe um erro, o site ficou lento do nada ou algo simplesmente "quebrou". O primeiro passo para resolver qualquer problema técnico no WordPress é entender o que está acontecendo nos bastidores. E para isso, existe o WP _ DEBUG.

Neste guia, vamos explicar o que é o WP _ DEBUG, como ativá-lo, como interpretar os logs de erro, quais ferramentas complementares usar e quais são as melhores práticas para debug em sites WordPress.

O Que é o WP _ DEBUG

O WP _ DEBUG é uma constante do PHP definida no arquivo wp-config.php do WordPress. Quando ativada, ela instrui o WordPress a exibir erros, avisos e notificações de PHP que normalmente ficam escondidos.

Por padrão, o WP _ DEBUG vem desativado em instalações WordPress:

define( 'WP_DEBUG', false );

Quando você muda para true , o WordPress começa a mostrar mensagens de erro que ajudam a identificar a origem de problemas:

define( 'WP_DEBUG', true );

Essas mensagens incluem erros fatais que derrubam o site, avisos sobre funções descontinuadas, notificações sobre variáveis não definidas e problemas de compatibilidade entre plugins e temas.

Como Ativar o WP _ DEBUG

Passo a passo

Acesse os arquivos do seu site via FTP, SFTP ou gerenciador de arquivos do painel de hospedagem.
Abra o arquivo wp-config.php , que fica na raiz da instalação WordPress.
Procure a linha que contém WP_DEBUG .
Altere de false para true .
Salve o arquivo.

Se a linha não existir, adicione antes da linha que diz /* That's all, stop editing! Happy publishing. */ :

define( 'WP_DEBUG', true );

A partir desse momento, erros de PHP serão exibidos no site.

WP DEBUG LOG: Salvando Erros em Arquivo

Exibir erros na tela do site não é prático e nem seguro, especialmente em sites de produção. O ideal é salvar os erros em um arquivo de log.

Para isso, ative o WP DEBUG LOG:

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

Com essa configuração, todos os erros são salvos no arquivo wp-content/debug.log . Você pode ler esse arquivo via FTP ou SSH.

Você também pode definir um caminho personalizado para o log:

define( 'WP_DEBUG_LOG', '/home/usuario/logs/wordpress-debug.log' );

Isso é útil para manter o log fora da pasta pública do site, por questões de segurança.

WP DEBUG DISPLAY: Escondendo Erros da Tela

Para evitar que erros apareçam na tela para os visitantes do site, use o WP DEBUG DISPLAY:

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

Essa é a configuração recomendada para sites em produção que precisam de debug. Os erros são salvos no log, mas não aparecem na tela.

Importante: Nunca deixe WP DEBUG DISPLAY como true em sites de produção. Mensagens de erro podem expor caminhos de arquivos, versões de PHP e outras informações que facilitam ataques.

SCRIPT _ DEBUG: Debugando CSS e JavaScript

O WordPress, por padrão, carrega versões minificadas dos seus arquivos CSS e JavaScript. Isso é bom para performance, mas dificulta o debug de problemas de frontend.

O SCRIPT _ DEBUG força o WordPress a carregar as versões completas (não minificadas):

define( 'SCRIPT_DEBUG', true );

Use quando:

Você está desenvolvendo um tema ou plugin
Precisa debugar um problema visual ou de comportamento JavaScript
Quer ver mensagens de erro mais claras no console do navegador

Desative depois de terminar o debug, pois os arquivos não minificados são maiores e mais lentos.

SAVEQUERIES: Monitorando Consultas ao Banco de Dados

O SAVEQUERIES salva todas as consultas SQL executadas pelo WordPress em um array, junto com o tempo de execução e a função que as chamou:

define( 'SAVEQUERIES', true );

Para ver as queries salvas, adicione este código ao seu tema (temporariamente):

if ( current_user_can( 'administrator' ) ) {
    global $wpdb;
    echo '<pre>';
    print_r( $wpdb->queries );
    echo '</pre>';
}

Ou use o plugin Query Monitor, que exibe essas informações de forma muito mais organizada.

Atenção: SAVEQUERIES consome memória e processamento. Nunca deixe ativado em produção.

Configuração Completa de Debug

Aqui está a configuração completa que recomendamos para debug em ambiente de desenvolvimento ou staging:

// Debug ativado
define( 'WP_DEBUG', true );

// Salva erros em arquivo
define( 'WP_DEBUG_LOG', true );

// Não exibe erros na tela
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

// Carrega scripts e estilos não minificados
define( 'SCRIPT_DEBUG', true );

// Salva queries do banco de dados
define( 'SAVEQUERIES', true );

E para produção (debug desativado):

define( 'WP_DEBUG', false );

Como Ler o debug.log

O arquivo wp-content/debug.log é um arquivo de texto simples. Cada linha registra um erro com:

Data e hora
Tipo de erro (Notice, Warning, Fatal error, Deprecated)
Mensagem descritiva
Arquivo e linha onde o erro ocorreu

Exemplo de log

[15-Mar-2026 14:32:01 UTC] PHP Warning: Undefined variable $price in /var/www/html/wp-content/plugins/meu-plugin/includes/class-product.php on line 42
[15-Mar-2026 14:32:01 UTC] PHP Deprecated: Function create_function() is deprecated in /var/www/html/wp-content/themes/meu-tema/functions.php on line 156
[15-Mar-2026 14:32:02 UTC] PHP Fatal error: Uncaught Error: Call to undefined function custom_function() in /var/www/html/wp-content/plugins/outro-plugin/main.php on line 89

Como interpretar

Warning (Aviso): Algo não está correto, mas o site continua funcionando. Deve ser corrigido, mas não é urgente.
Notice (Notificação): Informação sobre práticas de código que podem causar problemas. Menor prioridade.
Deprecated (Descontinuado): Uma função usada pelo plugin ou tema foi marcada como descontinuada. Funciona agora, mas pode parar em versões futuras do PHP ou WordPress.
Fatal error (Erro fatal): O site para de funcionar. Precisa ser corrigido imediatamente.

Erros Comuns de PHP no WordPress e Como Resolver

Undefined variable

PHP Warning: Undefined variable $variavel in arquivo.php on line X

Causa: Uma variável está sendo usada sem ter sido definida antes. Solução: Verifique se a variável foi inicializada antes do uso. Adicione verificações como isset() ou empty() .

Call to undefined function

PHP Fatal error: Call to undefined function nome_da_funcao() in arquivo.php on line X

Causa: O código tenta chamar uma função que não existe. Pode ser um plugin desativado, um arquivo não incluído ou um erro de digitação. Solução: Verifique se o plugin ou tema que define essa função está ativo. Confira se o nome da função está correto.

Allowed memory size exhausted

PHP Fatal error: Allowed memory size of 67108864 bytes exhausted in arquivo.php on line X

Causa: O PHP ficou sem memória para executar o script. Solução: Aumente o limite de memória no wp-config.php: define( 'WP_MEMORY_LIMIT', '256M' );

Maximum execution time exceeded

PHP Fatal error: Maximum execution time of 30 seconds exceeded in arquivo.php on line X

Causa: O script demorou mais tempo do que o permitido pelo PHP. Solução: Aumente o tempo no php.ini: max_execution_time = 120 . Ou identifique a operação que está demorando e otimize.

Deprecated function

PHP Deprecated: Function nome_funcao() is deprecated since version X.X in arquivo.php on line X

Causa: O código usa uma função que foi descontinuada pelo WordPress ou PHP. Solução: Atualize o plugin ou tema que contém essa função. Se for código próprio, substitua pela função recomendada.

Headers already sent

Warning: Cannot modify header information - headers already sent by (output started at arquivo.php:X)

Causa: O PHP tentou enviar headers HTTP depois que alguma saída (output) já foi enviada. Geralmente causado por espaço em branco antes da tag <?php ou por echo/print antes de wp_redirect() . Solução: Remova espaços ou caracteres antes de <?php . Verifique se não há output antes de funções que modificam headers.

Query Monitor: O Plugin Essencial para Debug

O Query Monitor é o melhor plugin de debug para WordPress. Ele não usa WP _ DEBUG (embora funcione bem junto) e oferece informações detalhadas sobre:

Consultas SQL (quantidade, tempo, duplicadas, lentas)
Erros de PHP
Hooks e filtros executados
Requisições HTTP feitas pelo WordPress
Uso de memória
Scripts e estilos enfileirados
Transients do banco de dados
Variáveis de ambiente
Regras de rewrite

Como usar

Instale e ative o plugin Query Monitor pelo painel do WordPress.
Uma barra aparece no topo do site (visível só para administradores).
Clique em qualquer métrica para ver detalhes.
Filtre por plugin, tema ou componente para encontrar o problema.

O Query Monitor é seguro para usar em produção porque só exibe informações para administradores logados. Mesmo assim, recomendamos desativá-lo quando não estiver em uso para evitar consumo desnecessário de recursos.

Debug Bar: Alternativa e Complemento

O Debug Bar é outro plugin útil que adiciona uma barra de debug ao painel administrativo. Ele mostra:

Informações sobre a query principal do WordPress
Cache de objetos
Requisições HTTP
Constantes do WordPress

O Debug Bar tem extensões que adicionam funcionalidades extras:

Debug Bar Console: Executa código PHP e SQL no painel
Debug Bar Cron: Mostra tarefas agendadas do WP-Cron
Debug Bar Transients: Lista todos os transients do banco

Para a maioria dos casos, o Query Monitor é mais completo. Mas o Debug Bar pode ser útil como complemento em situações específicas.

Melhores Práticas de Logging

Use error _ log() para mensagens personalizadas

Além dos erros automáticos do PHP, você pode adicionar mensagens próprias ao debug.log:

error_log( 'Minha mensagem de debug' );
error_log( print_r( $minha_variavel, true ) );

Isso é útil para rastrear o fluxo de execução do código ou verificar o valor de variáveis em pontos específicos.

Filtre o log por data

O debug.log pode crescer rapidamente. Use o terminal para filtrar por data ou termo:

grep "15-Mar-2026" wp-content/debug.log
grep "Fatal error" wp-content/debug.log
tail -f wp-content/debug.log

O tail -f mostra as novas linhas em tempo real, o que é útil para monitorar erros enquanto você testa o site.

Rotacione o log

Configure uma rotação para que o debug.log não cresça indefinidamente:

# Rotaciona quando o arquivo passa de 10MB
if [ $(stat -f%z wp-content/debug.log 2>/dev/null || echo 0) -gt 10485760 ]; then
    mv wp-content/debug.log wp-content/debug.log.old
fi

Ou use logrotate se estiver em um servidor Linux com acesso root.

Desativando Debug em Produção

Depois de resolver o problema, desative o debug em produção:

define( 'WP_DEBUG', false );

Motivos para desativar:

Segurança: Mensagens de erro expõem informações sensíveis (caminhos de arquivos, versões de software).
Performance: O debug consome recursos extras do servidor.
Experiência do usuário: Ninguém quer ver mensagens de erro PHP ao visitar um site.

Se você precisa monitorar erros em produção sem exibir na tela, use a combinação WP_DEBUG = true + WP_DEBUG_LOG = true + WP_DEBUG_DISPLAY = false . Mas monitore o tamanho do arquivo debug.log.

Níveis de Erro do PHP

O PHP classifica os erros em níveis. Entender esses níveis ajuda a priorizar o que corrigir:

Nível	Constante	Descrição
Warning	E _ WARNING	Indica um problema, mas o script continua.
Notice	E _ NOTICE	Informação sobre código que pode causar problema.
Deprecated	E _ DEPRECATED	Função descontinuada que será removida.
Parse Error	E _ PARSE	Erro de sintaxe. O script nem executa.
Strict	E _ STRICT	Sugestões para melhorar o código.

Em desenvolvimento, configure o PHP para mostrar todos os níveis:

error_reporting( E_ALL );

Em produção, mostre apenas erros fatais:

error_reporting( E_ERROR | E_PARSE );

Xdebug: Debug Avançado para Desenvolvedores

Para desenvolvedores que precisam de debug mais profundo, o Xdebug é a ferramenta certa. Ele é uma extensão do PHP que adiciona:

Step debugging: Execute o código linha por linha, inspecionando variáveis em cada passo.
Stack traces: Veja toda a cadeia de chamadas de função que levou a um erro.
Profiling: Analise quanto tempo cada função leva para executar.
Code coverage: Veja quais linhas de código são executadas durante testes.

Configuração básica do Xdebug

No arquivo php.ini :

[xdebug]
zend_extension=xdebug
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_host=127.0.0.1
xdebug.client_port=9003

O Xdebug se integra com IDEs como VS Code (com a extensão PHP Debug), PhpStorm e outros. Você coloca breakpoints no código e inspeciona variáveis em tempo real.

Atenção: O Xdebug nunca deve ser instalado em servidores de produção. Ele consome muitos recursos e pode expor informações sensíveis.

Conclusão

Debugar WordPress não é um bicho de sete cabeças. Com as ferramentas certas e uma abordagem sistemática, você consegue identificar e resolver a maioria dos problemas:

Ative o WP DEBUG e WP DEBUG _ LOG
Leia o debug.log e identifique o erro
Use o Query Monitor para informações mais detalhadas
Corrija o problema no plugin, tema ou código que está causando o erro
Desative o debug em produção

Se você não tem tempo ou conhecimento técnico para debugar seu site WordPress, a HOSTWP cuida disso para você. Nosso time resolve problemas técnicos todos os dias para empresas no Rio de Janeiro e em todo o Brasil.

Fale com a HOSTWP no WhatsApp e resolva o problema do seu site WordPress hoje.