Debug WordPress: o que é, como ativar e dicas práticas
O modo debug (depuração) do WordPress é um recurso que permite registrar mensagens de erro para que você possa solucionar os problemas do seu site de maneira mais precisa. Ele é fundamental para manter seu site funcionando, especialmente depois de adicionar códigos personalizados que podem causar problemas.
Este tutorial explicará como funciona o modo debug do WordPress e todas as maneiras de ativá-lo. Cada um dos métodos listados se adequará a um tipo de tarefa de solução de problemas — portanto, escolha com base em suas necessidades. Vamos lá?
Conteúdo
O que é debug no WordPress?
O debug do WordPress é um recurso que permite aos desenvolvedores listar as mensagens de erro geradas pela plataforma para solucionar problemas. É possível ativá-lo com algumas variáveis globais do PHP, como WP_DEBUG e SCRIPT_DEBUG. Como alternativa, você pode depurar o WordPress realizando a exibição de dados importantes, como a execução de scripts, usando um plugin.
Como ativar o debug do WordPress com programação
Nesta seção, explicaremos como ativar o modo de debug do WordPress usando quatro variáveis PHP, que diferem com base nas suas necessidades.
1. Ative o WP_DEBUG
Ativar o WP_DEBUG é a maneira mais básica de iniciar o debug no WordPress. Ele pode verificar se há problemas de código PHP em diferentes componentes do site, incluindo temas e plugins.
Para usar a variável global WP_DEBUG, basta alterar seu valor no arquivo wp-config.php de FALSE para TRUE. Antes de fazer isso, verifique se é possível acessar a pasta raiz do WordPress usando um aplicativo de protocolo de transferência de arquivos (FTP), como o FileZilla, ou o gerenciador de arquivos do seu provedor de hospedagem.
Se você usar um cliente FTP, será necessário fazer o download do arquivo PHP, editá-lo no computador e enviá-lo novamente para o site.
Para simplificar o processo, usaremos o Gerenciador de Arquivos da Hostinger, que permite editar o wp-config.php diretamente no seu navegador. Siga os passos abaixo:
- Faça login no hPanel. Navegue até Sites → Painel → Gerenciador de Arquivos.
- Vá para a pasta raiz public_html do WordPress.
- Abra o arquivo wp-config.php clicando duas vezes nele.
- Encontre a seguinte linha. Se você não conseguir localizar essa entrada, adicione-a manualmente após a linha $table_prefix = ‘wp_’;:
define( 'WP_DEBUG', false );
- Altere o valor de FALSE para TRUE.
- Clique no ícone de disquete no canto superior direito do editor para salvar as alterações.
É isso! Se você encontrar problemas com o PHP, o WordPress exibirá a mensagem de erro no front-end.
O WordPress fornece algumas variáveis PHP adicionais para modificar o modo de depuração. Por exemplo, WP_DEBUG_DISPLAY oculta as mensagens de erro no front-end quando definida como FALSE, para não atrapalhar a experiência do usuário.
Os desenvolvedores geralmente a utilizam junto com a WP_DEBUG_LOG, que lista os problemas do PHP no arquivo debug.log dentro do diretório wp-content. Como o WP_DEBUG, você adiciona essas variáveis ao wp-config.php acima da linha “That’s all, stop editing!” (Isso é tudo, pare de editar!). Sua configuração deve ficar parecida com o código a seguir:
if ( ! defined( 'WP_DEBUG' ) ) {
define( 'WP_DEBUG', true );
define('WP_DEBUG_DISPLAY', false);
define('WP_DEBUG_LOG', true);
}
Lembre-se de que o WordPress registrará apenas as mensagens que ocorrerem depois que você ativar a variável WP_DEBUG_LOG. Se você quiser registrar problemas anteriores, será necessário manualmente.
Importante! Se você quiser desativar o modo de depuração do WordPress, lembre-se de definir WP_DEBUG_DISPLAY e WP_DEBUG_LOG como FALSE para evitar que esses recursos sejam executados indefinidamente e desperdicem recursos.
2. Ative o SCRIPT_DEBUG
Por padrão, o WordPress executa arquivos principais de JavaScript (JS) e CSS minificados que ocultam recursos não essenciais, como mensagens de erro. Embora esse comportamento ajude a melhorar a velocidade do seu site, ele pode tornar a solução de problemas mais complicada, pois você não consegue ver as informações detalhadas dos erros.
Para depurar os arquivos JS e CSS, você pode ativar as versões de desenvolvimento deles usando a variável SCRIPT_DEBUG. Ela é especialmente útil caso você tenha modificado o visual do seu site usando essas linguagens de programação.
As etapas para ativar o SCRIPT_DEBUG são semelhantes às do WP_DEBUG. Veja como fazê-lo usando o Gerenciador de Arquivos da Hostinger:
- Abra a pasta raiz public_html do WordPress.
- Clique duas vezes no arquivo wp-config.php para abri-lo.
- Localize a linha abaixo e altere seu valor de FALSE para TRUE. Se não encontrá-la, adicione-a antes da linha “That’s all stop editing“.
define( 'SCRIPT_DEBUG', true );
- Clique no ícone de disquete no canto superior direito para salvar as alterações.
Agora, se seu site encontrar problemas relacionados ao CSS ou ao JavaScript, ele deverá exibir as mensagens de erro completas. Após solucionar os problemas que você quer corrigir, lembre-se de desativar essa variável e reativar os arquivos minificados para evitar problemas de desempenho.
3. Ative o log file do PHP
O PHP possui a função error_log() integrada, que permite registrar problemas relacionados à linguagem. Esse recurso é executado no nível do servidor, o que significa que ele pode depurar todos os aplicativos PHP em seu ambiente de hospedagem, inclusive o WordPress e seu banco de dados.
Você pode ativar o debug log do PHP usando o arquivo php.ini. No entanto, vários provedores de hospedagem desativam esse recurso devido a questões de design e segurança.
Se você usa os planos de hospedagem WordPress da Hostinger, é possível ativar esse recurso por meio do hPanel. Veja como:
- Faça login no hPanel e vá para Sites → Painel → Barra lateral → Avançado → Configuração de PHP.
- Selecione a guia Opções de PHP.
- Ative a caixa logErrors para ativar o registro. Se você quiser exibir a mensagem de erro no front end, ative a opção displayErrors. Recomendamos deixá-la desmarcada.
- Role a tela para baixo e pressione Salvar.
Você pode acessar o arquivo de registro abrindo o diretório .log na pasta raiz do seu servidor. Veja como fazer isso no Gerenciador de Arquivos da Hostinger:
- No painel do hPanel, navegue até a barra lateral → Arquivos → Gerenciador de arquivos.
- Clique no botão Acessar todos os arquivos de hospedagem.
- Abra a pasta .log. Se você não encontrar esse diretório, ele pode estar oculto. Para exibi-lo, vá até a barra lateral → Configurações e desmarque a opção Ocultar dotfilesbox.
- Clique duas vezes no arquivo error_log_domain_tld para ver todos os erros de PHP em seu site, incluindo seus registros de data e hora e tipos.
4. Ative o relatório de erros do WPDB
Para depurar seu banco de dados do WordPress, ative a variável show_errorsvariable da classe wpdb. Essa configuração exibirá erros de SQL em seu site, o que ajuda a solucionar problemas de conexão com o banco de dados e erros de sintaxe.
Veja como ativar o relatório de erros do WPDB por meio do Gerenciador de Arquivos da Hostinger:
- Abra a pasta public_html do seu site WordPress e vá até a pasta wp-includes.
- Clique duas vezes no arquivo class-wpdb.php para abri-lo.
- Localize a linha class wpdb.
- Dentro de seus colchetes, localize a variável $show_errors e altere seu valor para TRUE, da seguinte forma:
public $show_errors = true;
- Clique no ícone do disquete para salvar as alterações.
Como ativar o debug WordPress usando um plugin
Se você não se sentir à vontade para mexer com programação diretamente, é possível ativar o modo de debug do WordPress usando um plugin. Por exemplo, o WP Debugging permite que você altere o valor da variável WP_DEBUG diretamente do painel de administração.
Depois de baixar e instalar o plugin por meio do painel do WordPress, siga estas etapas para ativar o modo de depuração:
- Vá para a barra lateral → Tools → WP Debugging.
- Marque a caixa Set WP_DEBUG to true. Opcionalmente, você pode definir se deseja que o WordPress mostre os problemas no front-end e ignore os erros fatais.
- Clique em Salvar alterações.
Para uma análise mais completa do que o recurso de debug padrão do WordPress, recomendamos o Query Monitor. Ele exibe dados para solucionar problemas de consultas a bancos de dados, chamadas PHP e execuções de scripts.
Depois de instalar o plugin, um menu será exibido em sua barra de administração. Ao clicar nele, você tem acesso a uma janela que detalha várias categorias de dados, como:
- Overview (Visão geral) – mostra um resumo do processo de carregamento de seu site WordPress, incluindo o número de consultas, o uso de memória e o tempo de geração de páginas.
- Database Queries (Consultas ao banco de dados) – lista todas as chamadas que o WordPress envia ao banco de dados ao carregar uma página da web, o que é útil para verificar erros de sintaxe SQL ou problemas de conectividade.
- Logs – contém todas as mensagens de erro dos componentes PHP do seu site WordPress que usam a ação qm/debug, como plugins.
- Scripts – exibe todos os arquivos JavaScript que o WordPress carrega ao renderizar uma página da web, incluindo sua posição, origem e host.
- Styles (Estilos) – contém uma lista de arquivos CSS que o WordPress usa para renderizar o conteúdo de uma página da web, incluindo seu manipulador e posição.
Vários recursos do Query Monitor, como o registro de erros, não funcionarão imediatamente, e você deverá adicionar o código de rastreamento manualmente ao plugin. Felizmente, o próprio software traz um manual em cada seção para orientar você nessa configuração.
Observe que todos os usuários conectados ao WordPress podem ver o menu do plugin, o que pode expor informações confidenciais. Para ocultar as informações de depuração, oculte a barra de administração do WordPress para todas as contas, exceto para os administradores.
Precisa de ajuda para solucionar problemas em seu site?
O Solucionador de Problemas com IA da hospedagem WordPress da Hostinger avisa automaticamente sobre qualquer problema em seu site. Você pode resolvê-los facilmente clicando no botão Corrigir erros no hPanel.
Debug WordPress: dicas práticas
Agora, vamos passar por algumas práticas recomendadas para um processo de solução de problemas eficaz e seguro ao fazer debug do WordPress.
Evite que as mensagens de erro sejam exibidas aos visitantes do site
Embora as mensagens de erro te ajudem a identificar problemas, exibi-las no front-end pode prejudicar a experiência do usuário.
Uma página de erro padrão também faz com que seu site pareça menos confiável. Para evitar isso, configure um redirecionamento para outra página, permitindo que os visitantes continuem a navegar em seu site normalmente.
Além disso, algumas mensagens de erro podem exibir partes do código do seu site WordPress. Isso pode gerar um risco de segurança, pois invasores podem usar essas informações para encontrar possíveis pontos de entrada no seu site.
Ative o modo de manutenção do WordPress
Ao depurar ou solucionar problemas, recomendamos ativar o modo de manutenção do WordPress. Esse recurso oculta todas as mensagens de erro e redireciona os visitantes para uma landing page específica.
Os usuários da Hostinger podem ativar facilmente o modo de manutenção no hPanel. Vá para Sites → Painel → WordPress → Visão geral. Em seguida, ative o botão do modo de manutenção.
Observe que esse recurso redireciona os usuários para a página de manutenção padrão da Hostinger. Se você quiser um design personalizado, use um plugin como o LightStart.
Use um ambiente de testes
Depois de depurar um erro, recomendamos testar a solução em um ambiente de testes antes de implementá-la no seu site real.
Os usuários dos planos Business ou superiores da Hostinger podem configurar facilmente um ambiente de testes do WordPress acessando hPanel → Sites → Painel → WordPress → Teste e clicando no botão Criar teste.
Como alternativa, você também pode configurar um site de teste usando um plugin como o WP Staging ou instalar um ambiente WordPress localmente em seu computador usando uma pilha como o XAMPP.
Conclusão
O modo de debug do WordPress permite que os desenvolvedores exibam e registrem mensagens de erro para facilitar a solução de problemas. Para ativá-lo, acesse o diretório raiz do seu site e abra o arquivo wp-config.php, definindo as variáveis WP_DEBUG e WP_DEBUG_LOG como TRUE.
Para exibir erros nos arquivos CSS e JavaScript, ative a versão de desenvolvimento dessas linguagens de programação. Basta abrir o arquivo wp-config.php e defina o parâmetro SCRIPT_DEBUG como TRUE.
Você também pode ativar o recurso de registro de erros do PHP ativando a função log_error() no arquivo php.ini. Como alternativa, os usuários da Hostinger podem fazer isso facilmente ativando o recurso logErrors no menu Configuração do PHP do hPanel.
Para verificar problemas do banco de dados, defina a variável $show_errors em public_html/wp-includes/class-wpdb.php como TRUE. Se você não se sentir à vontade para editar o código do seu site diretamente, é possível ativar o WP_DEBUG usando o plugin WP Debugging ou verificar os dados diretamente usando o Query Monitor.
Perguntas frequentes sobre debug WordPress
Por fim, vamos responder algumas das perguntas mais frequentes sobre a depuração de erros no WordPress.
Como verificar se o debug está ativado no WordPress?
Para verificar se o modo de debug do WordPress está ativado, abra a pasta public_html do seu site usando um cliente FTP ou o gerenciador de arquivos do seu provedor de hospedagem. Abra o arquivo wp-config.php e verifique se o valor define( ‘WP_DEBUG’, true) está definido como TRUE. FALSE significa que a depuração está desativada.
Como ver todos os erros do WordPress?
Para listar todos os erros do WordPress, defina as variáveis WP_DEBUG_LOG e WP_DEBUG no wp-config.php como TRUE. Como alternativa, você pode ativar a função error_log() no php.ini. Os usuários da Hostinger podem fazer isso sem mexer em códigos ativando a configuração logErrors no menu Configurações de PHP do hPanel.
Por que não consigo gerar um registro de erros no WordPress?
Se o WordPress não estiver registrando os erros, a variável WP_DEBUG_LOG provavelmente está definida como FALSE. Além disso, você deve definir WP_DEBUG como TRUE e WP_DEBUG_DISPLAY como FALSE. Se você usar a função error_log() do PHP, o arquivo de registro de erros deverá estar localizado na pasta oculta .log.
Jornalista formado pela Universidade Federal da Bahia e Especialista em Marketing de Conteúdo na Hostinger, onde atuo na criação e otimização de artigos úteis, envolventes e criativos em áreas como desenvolvimento web e, marketing. Além disso, sou colaborador eventual do site MacMagazine e da editoria de cultura do Jornal A Tarde, fascinado por arte, culinária e tecnologia.
