Como Criar e Acessar Logs de Erros para WordPress (3 Métodos)

Os logs de erros do WordPress são registos de diagnóstico que capturam erros PHP, exceções fatais, falhas de base de dados, conflitos de plugins e incompatibilidades de temas à medida que ocorrem no seu servidor. Aceder e interpretar estes logs é a forma mais rápida de identificar a causa raiz de uma página quebrada, um ecrã branco da morte ou uma regressão de desempenho silenciosa — sem adivinhar ou desativar plugins um a um.

Este guia abrange três métodos testados em produção para ativar, localizar e ler logs de erros do WordPress: a pilha nativa WP_DEBUG, logs ao nível do servidor através do painel de controlo de alojamento, e visualizadores de logs baseados em plugins. Cada método é adequado para um nível de acesso e caso de uso diferente, e os três são explicados com caminhos de ficheiros exatos, sintaxe de configuração e considerações de segurança.

Por Que os Logs de Erros do WordPress São Importantes

O WordPress funciona em PHP, que gera várias classes de mensagens de tempo de execução: erros fatais (a execução para), avisos (a execução continua mas algo está errado), avisos informativos (informativos, frequentemente indicando código obsoleto) e mensagens deprecated (funções agendadas para remoção). Por padrão, nenhuma destas é escrita num log persistente na maioria das configurações de produção — são suprimidas ou enviadas para o navegador, o que representa um risco de segurança.

Sem um log, uma atualização de plugin que introduz um erro fatal produz apenas um ecrã em branco. Uma biblioteca SMTP mal configurada descarta emails silenciosamente. Uma violação do limite de memória mata o carregamento de uma página sem deixar rasto visível. Os logs de erros convertem estas falhas invisíveis em entradas com carimbo de data/hora, referência de ficheiro e número de linha nas quais pode agir imediatamente.

Método 1: Ativar o Modo de Depuração do WordPress via wp-config.php

O WordPress inclui um subsistema de depuração integrado controlado por um conjunto de constantes PHP definidas em wp-config.php. Este é o método mais preciso porque captura erros específicos do WordPress, incluindo os lançados pela API de plugins, pelo carregador de temas e pela camada de abstração de base de dados (wpdb).

Passo 1: Localizar e Abrir o wp-config.php

Ligue-se ao seu servidor via SFTP (preferível ao FTP simples por questões de segurança) usando um cliente como FileZilla ou Cyberduck, ou abra o Gestor de Ficheiros do seu fornecedor de alojamento. Navegue até ao diretório raiz do WordPress, normalmente /public_html/ ou /var/www/html/. O ficheiro wp-config.php encontra-se na raiz deste diretório.

Se tiver acesso SSH, pode editá-lo diretamente:

nano /var/www/html/wp-config.php

Passo 2: Configurar as Constantes de Depuração

Localize a linha existente:

define( 'WP_DEBUG', false );

Substitua o bloco completo pela seguinte configuração, que ativa o registo sem expor erros aos visitantes do site:

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

O que cada constante faz:

• WP_DEBUG — ativa o motor de depuração do WordPress e habilita o reporte de erros PHP ao nível E_ALL.
• WP_DEBUG_LOG — escreve todos os erros capturados num ficheiro de log em vez de (ou além de) no ecrã.
• WP_DEBUG_DISPLAY — quando definido como false, suprime a saída no ecrã. Isto é crítico em sites de produção; sem isto, os avisos PHP expõem caminhos de ficheiros internos e nomes de variáveis aos visitantes.
• display_errors — a diretiva PHP subjacente; defini-la como 0 via ini_set fornece uma segunda camada de supressão caso um plugin ou tema substitua WP_DEBUG_DISPLAY.

Passo 3: Localizar o Ficheiro de Log de Depuração

Com WP_DEBUG_LOG definido como true, o WordPress escreve os erros em:

/wp-content/debug.log

Este ficheiro é criado automaticamente no primeiro erro registado. Pode visualizá-lo via SFTP ou SSH:

tail -f /var/www/html/wp-content/debug.log

O sinalizador tail -f transmite novas entradas em tempo real, o que é inestimável ao reproduzir um erro específico de forma interativa.

Passo 4: Usar um Caminho de Log Personalizado (Recomendado por Segurança)

O caminho padrão debug.log é publicamente acessível se o seu servidor web não o bloquear explicitamente. Um servidor mal configurado servirá https://yourdomain.com/wp-content/debug.log a qualquer visitante, expondo caminhos internos, prefixos de tabelas de base de dados e nomes de classes.

Opção A — Mover o ficheiro de log para fora da raiz web:

define( 'WP_DEBUG_LOG', '/var/log/wordpress/debug.log' );

Crie o diretório de destino e defina as permissões:

mkdir -p /var/log/wordpress
chown www-data:www-data /var/log/wordpress
chmod 750 /var/log/wordpress

Opção B — Bloquear o caminho padrão via .htaccess (Apache):

<Files "debug.log">
    Order allow,deny
    Deny from all
</Files>

Opção C — Equivalente Nginx no seu bloco de servidor:

location ~* /wp-content/debug.log {
    deny all;
    return 404;
}

Passo 5: Desativar o Modo de Depuração Após a Resolução de Problemas

Nunca deixe WP_DEBUG definido como true num site em produção por mais tempo do que o necessário. Assim que o problema estiver resolvido:

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

Deixar o modo de depuração ativo num site de produção degrada o desempenho (o PHP processa cada aviso E_ALL) e pode expor rastreamentos de pilha sensíveis se WP_DEBUG_DISPLAY for acidentalmente definido como true.

Método 2: Aceder aos Logs de Erros ao Nível do Servidor via Painel de Controlo de Alojamento

Os erros do WordPress que ocorrem antes de o arranque do WordPress ser concluído — como um wp-config.php corrompido, uma incompatibilidade de versão PHP ou uma falha de ligação à base de dados — nunca aparecerão em debug.log porque o próprio WordPress nunca carrega. Para estes, precisa do log de erros PHP do servidor ou do log de erros Apache/Nginx.

Alojamento Baseado em cPanel

Se o seu ambiente de alojamento utiliza VPS com cPanel, o log de erros está acessível através da interface do painel de controlo:

1. Inicie sessão no cPanel.
2. Navegue até Métricas > Erros.
3. O painel exibe as últimas 300 linhas do log de erros Apache da sua conta.

Para o ficheiro de log completo, use o Gestor de Ficheiros do cPanel ou ligue-se via SFTP e navegue até:

/home/yourusername/logs/yourdomain.com-ssl_log
/home/yourusername/logs/yourdomain.com-error_log

Os nomes exatos dos ficheiros variam consoante a configuração do servidor, mas o padrão é consistente na maioria das instalações cPanel.

Alojamento Baseado em Plesk

No Plesk, navegue até Sites & Domínios > selecione o seu domínio > Logs. Pode filtrar por tipo de log (acesso, erro, PHP) e descarregar o ficheiro de log completo.

Acesso Direto ao Servidor (VPS ou Dedicado)

Num ambiente de Alojamento VPS ou Servidor Dedicado onde tem acesso root, as localizações dos logs dependem da sua pilha:

Para monitorizar o log PHP-FPM em tempo real:

tail -f /var/log/php8.2-fpm.log

Para pesquisar erros fatais específicos do WordPress no log Apache:

grep -i "fatal|wordpress|wp-" /var/log/apache2/error.log | tail -50

Configurar o Registo de Erros PHP ao Nível do Servidor

Se os erros PHP não estiverem a ser escritos num log, verifique a sua configuração php.ini:

php --ini | grep "Loaded Configuration"

Abra o ficheiro php.ini identificado e verifique ou defina:

log_errors = On
error_log = /var/log/php_errors.log
display_errors = Off
error_reporting = E_ALL

Reinicie o PHP-FPM após as alterações:

systemctl restart php8.2-fpm

Em alternativa, substitua as definições PHP por site usando um ficheiro .htaccess (apenas Apache):

php_flag log_errors on
php_value error_log /var/log/wordpress/php_errors.log
php_flag display_errors off

Método 3: Usar um Plugin de Registo de Erros do WordPress

Para ambientes onde o acesso direto ao servidor é restrito — como Alojamento Web Partilhado — ou para equipas onde administradores não técnicos precisam de rever erros sem acesso SSH, um plugin WordPress oferece uma alternativa viável.

Plugins Recomendados

• WP Log Viewer — lê o ficheiro debug.log existente e exibe-o no painel de administração do WordPress com filtragem e pesquisa.
• Error Log Monitor — adiciona um widget ao painel de controlo mostrando erros recentes e pode enviar alertas por email quando novos erros são registados.
• Query Monitor — vai além do registo de erros para analisar consultas de base de dados, chamadas à API HTTP, hooks e etiquetas condicionais. Essencial para depuração de desempenho.
• Health Check & Troubleshooting — plugin oficial do WordPress.org; ativa um modo de resolução de problemas que ativa um tema padrão e desativa todos os plugins apenas para a sua sessão, sem afetar outros visitantes.

Instalar e Configurar o Error Log Monitor

1. No painel de administração do WordPress, vá a Plugins > Adicionar Novo.
2. Pesquise por Error Log Monitor e clique em Instalar Agora, depois em Ativar.
3. Navegue até Definições > Error Log Monitor.
4. Defina o caminho do ficheiro de log. Se tiver movido debug.log para fora da raiz web, introduza aqui o caminho absoluto do servidor.
5. Configure a frequência de alertas por email se pretender notificações para novos tipos de erros.

O plugin lê o mesmo ficheiro debug.log para o qual WP_DEBUG_LOG escreve. Não cria um mecanismo de registo separado — é um visualizador. Isto significa que WP_DEBUG e WP_DEBUG_LOG ainda têm de estar ativados em wp-config.php para que o plugin exiba algo.

Limitação crítica: Os plugins carregam após o arranque do WordPress. Qualquer erro que impeça o WordPress de carregar (falha de ligação à base de dados, ficheiro de núcleo corrompido, versão PHP incompatível) não será visível em nenhum visualizador de logs baseado em plugins. Para esses cenários, o Método 2 é a única opção.

Comparação: Três Métodos de Registo de Erros do WordPress

Leitura e Interpretação de Entradas do Log de Erros do WordPress

Uma entrada bruta de debug.log tem este aspeto:

[04-Jul-2025 14:32:11 UTC] PHP Fatal error: Uncaught Error: Call to undefined function get_field() in /var/www/html/wp-content/themes/mytheme/functions.php:47
Stack trace:
#0 /var/www/html/wp-content/themes/mytheme/functions.php(47): get_field()
#1 {main}
thrown in /var/www/html/wp-content/themes/mytheme/functions.php on line 47

Como ler isto:

• O carimbo de data/hora está em UTC — converta para o fuso horário local do seu servidor se necessário.
• PHP Fatal error significa que a execução parou. A página que desencadeou isto devolveu um erro 500 ou um ecrã em branco.
• Call to undefined function get_field() significa que o plugin Advanced Custom Fields está desativado ou carregado após o functions.php do tema ter tentado chamá-lo.
• O rastreamento de pilha mostra o ficheiro exato e o número de linha. Comece a depurar na linha 47 de functions.php.

Padrões de erros comuns e as suas causas:

• PHP Warning: require(): Failed opening required — um caminho de ficheiro está errado ou um ficheiro está em falta. Frequentemente causado por um plugin que referencia um ficheiro que foi eliminado.
• PHP Deprecated: Function _register_controls is deprecated — um plugin ou tema usa uma API desatualizada. Não é fatal, mas indica um plugin que não foi atualizado para a versão atual do WordPress/Elementor.
• WordPress database error ... for query — uma consulta wpdb falhou. Verifique se há incompatibilidades de prefixo de tabela ou tabelas corrompidas.
• Maximum execution time of 30 seconds exceeded — um script demorou demasiado tempo. Comum com importações grandes, consultas não otimizadas ou chamadas a APIs externas que expiram.
• Allowed memory size of X bytes exhausted — o PHP atingiu o limite de memória. Aumente memory_limit em php.ini ou identifique o plugin com fuga de memória.

Melhores Práticas para Gerir Logs de Erros do WordPress

Faça rotação de logs para evitar esgotamento do disco. Um site WordPress movimentado sob ataque ou com um erro recorrente pode gerar centenas de megabytes de dados de log por dia. Em servidores Linux, configure logrotate:

nano /etc/logrotate.d/wordpress-debug

/var/log/wordpress/debug.log {
    daily
    rotate 14
    compress
    missingok
    notifempty
    create 640 www-data www-data
}

Nunca confirme debug.log para controlo de versões. Adicione-o ao .gitignore:

wp-content/debug.log

Audite o seu wp-config.php após cada migração de servidor. As migrações de alojamento frequentemente repõem WP_DEBUG para false ou introduzem um novo modelo wp-config.php que substitui as suas constantes.

Use SAVEQUERIES para depuração ao nível da base de dados. Adicione esta constante juntamente com WP_DEBUG para registar cada consulta SQL que o WordPress executa:

define( 'SAVEQUERIES', true );

Depois inspecione $wpdb->queries num modelo personalizado ou via Query Monitor. Desative-o imediatamente após o uso — armazena cada consulta em memória e aumenta significativamente o consumo de RAM.

Correlacione os carimbos de data/hora dos logs com eventos de implementação. Se aparecer um novo tipo de erro, verifique se coincide com uma atualização de plugin, uma atualização do núcleo do WordPress ou uma alteração de versão PHP no servidor. A maioria dos painéis de controlo de alojamento regista as alterações de versão PHP numa trilha de auditoria separada.

Matriz de Decisão: Qual Método Usar

Lista de Verificação Técnica de Pontos-Chave

• Defina WP_DEBUG_DISPLAY como false antes de ativar WP_DEBUG_LOG em qualquer site com tráfego em direto.
• Mova debug.log para fora da raiz web ou bloqueie-o via regras do servidor — o caminho padrão é publicamente acessível.
• Use tail -f no ficheiro de log ao reproduzir erros de forma interativa; elimina a necessidade de atualizar o ficheiro manualmente.
• Os logs PHP e Apache/Nginx ao nível do servidor são a única fonte de verdade para erros que ocorrem antes de o WordPress carregar.
• Os visualizadores de logs baseados em plugins requerem que WP_DEBUG_LOG esteja ativo — são leitores, não escritores.
• Implemente rotação de logs em qualquer servidor onde WP_DEBUG_LOG esteja ativado por mais de algumas horas.
• Nunca deixe SAVEQUERIES ativado em produção; é um encargo de memória e desempenho.
• Após resolver um problema, defina todas as constantes de depuração de volta para false e verifique com um pedido do navegador que não aparecem avisos PHP no código-fonte da página.

—

Perguntas Frequentes

Onde está localizado o ficheiro de log de depuração do WordPress por padrão?

O WordPress escreve o log de depuração em /wp-content/debug.log relativamente ao diretório raiz do WordPress. Este caminho só é criado após o primeiro erro ser registado e apenas quando tanto WP_DEBUG como WP_DEBUG_LOG estão definidos como true em wp-config.php. Pode substituir o caminho passando uma string de caminho de ficheiro absoluto como valor de WP_DEBUG_LOG em vez de true.

É seguro ativar o WP_DEBUG num site de produção em direto?

É seguro apenas se WP_DEBUG_DISPLAY estiver explicitamente definido como false e display_errors estiver definido como 0. Sem estas duas definições, os erros PHP — incluindo caminhos de ficheiros internos e nomes de tabelas de base de dados — são renderizados diretamente no código-fonte HTML de cada página. Associe sempre WP_DEBUG true com WP_DEBUG_DISPLAY false em qualquer site com tráfego público.

Por que o meu ficheiro debug.log está vazio mesmo com o WP_DEBUG ativado?

As causas mais comuns são: o processo do servidor web não tem permissão de escrita no diretório /wp-content/; WP_DEBUG_LOG está definido como false ou está ausente de wp-config.php; ou o erro está a ocorrer ao nível do servidor antes de o WordPress carregar, o que significa que aparecerá no log Apache ou PHP-FPM em vez de debug.log. Verifique as permissões do diretório com ls -la wp-content/ e confirme que as constantes estão definidas na ordem correta em wp-config.php.

Qual é a diferença entre WP_DEBUG_LOG e o log de erros PHP do servidor?

WP_DEBUG_LOG é uma constante ao nível do WordPress que encaminha os erros capturados pelo gestor de erros personalizado do WordPress para debug.log. O log de erros PHP do servidor (configurado via error_log em php.ini) captura todos os erros PHP ao nível do interpretador, incluindo os que ocorrem antes de o WordPress inicializar. Num servidor corretamente configurado, ambos os logs estão ativos simultaneamente e complementam-se mutuamente.

Posso ativar o registo de erros em alojamento partilhado sem acesso SSH?

Sim. Pode editar wp-config.php através do Gestor de Ficheiros do seu fornecedor de alojamento no cPanel ou Plesk, ativar WP_DEBUG e WP_DEBUG_LOG, e depois ler debug.log através da mesma interface do Gestor de Ficheiros. Para logs ao nível do servidor em Alojamento Web Partilhado, use a secção Erros em Métricas no cPanel. Se precisar de um controlo mais granular sobre a configuração PHP e os caminhos de log, atualizar para um plano de Alojamento VPS dá-lhe acesso direto ao php.ini e acesso SSH completo a todos os ficheiros de log.