Onde fica o debug.log do WordPress e como mover o arquivo de lugar

O WordPress grava o log de depuração em wp-content/debug.log por padrão — um caminho absoluto do tipo /caminho/para/seu/site/wp-content/debug.log no disco. O arquivo não existe até algo ser realmente registrado, e só é gravado quando WP_DEBUG está como true e WP_DEBUG_LOG está ligado no wp-config.php. Esse local padrão também é um problema de segurança concreto, porque na maioria das hospedagens qualquer pessoa consegue baixá-lo pelo navegador.

As três constantes e o que cada uma faz

As três vão no wp-config.php, acima da linha que diz /* That's all, stop editing! Happy blogging. */. Qualquer coisa colocada abaixo dessa linha roda depois que o WordPress já subiu e é ignorada.

Constante	Padrão	O que faz
WP_DEBUG	false	Chave geral. Eleva o nível de relatório de erros do PHP para mostrar avisos, alertas e recursos obsoletos. Nada mais desta lista funciona sem ela.
WP_DEBUG_LOG	false	Manda os erros para um arquivo. true significa wp-content/debug.log. Uma string é tratada como o caminho do arquivo onde gravar.
WP_DEBUG_DISPLAY	true	Imprime os erros dentro do HTML da página, visíveis para todo visitante.

A dependência é a parte que passa despercebida. O WP_DEBUG_LOG é lido dentro do bloco do WP_DEBUG no código de inicialização do WordPress. Se o WP_DEBUG está como false, deixar o WP_DEBUG_LOG como true não faz absolutamente nada — nenhum arquivo, nenhum erro, nenhum aviso. Se você adicionou o WP_DEBUG_LOG e nenhum log apareceu, confira o WP_DEBUG primeiro.

Uma configuração que funciona em site no ar:

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

Se o WP_DEBUG já estiver definido mais acima no arquivo — e normalmente está, com valor false —, edite essa linha existente em vez de acrescentar um segundo define(). Definir a mesma constante duas vezes gera um aviso do PHP que, num site com exibição ligada, aparece bem no topo da página.

Por que o WP_DEBUG_DISPLAY precisa ser false em produção

Com a exibição ligada, os erros do PHP são jogados dentro da resposta HTML. Um único aviso de função obsoleta vindo do tema imprime o caminho absoluto do seu servidor para todo visitante. Um erro de banco imprime nomes de tabelas e pedaços de consulta. Pior: conteúdo impresso antes do envio dos cabeçalhos quebra redirecionamentos, quebra respostas REST e AJAX que esperam JSON limpo e pode gerar aquela tela branca que as pessoas depois culpam num plugin.

Uma sutileza que vale saber: deixar o WP_DEBUG_DISPLAY como null não é a mesma coisa que false. O null diz ao WordPress para não mexer na configuração display_errors do PHP e herdar o que o servidor definiu. O false desliga ativamente. Em site de produção, use false e acrescente a linha do ini_set acima como cinto e suspensório, já que um plugin pode religar o display_errors mais adiante na requisição.

O local padrão pode ser baixado por qualquer um

O wp-content/debug.log fica dentro da raiz do site. Nada numa instalação padrão do WordPress bloqueia requisições diretas a ele. Num Apache ou nginx comum, https://seusite.com.br/wp-content/debug.log devolve o arquivo em texto puro. Logs de depuração contêm caminhos absolutos do servidor, detalhes internos de plugins e temas, erros de banco com o texto real das consultas e, às vezes, valores passados a funções que falharam. Isso é reconhecimento de graça para quem adivinhar a URL — e é uma das primeiras URLs que scanners automatizados testam.

Existem duas formas de lidar com isso. A melhor é mover o log.

Mova o log usando um caminho

Desde o WordPress 5.1, o WP_DEBUG_LOG aceita um caminho de arquivo em string no lugar de um booleano. Aponte para um lugar fora do diretório público:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', '/home/seuusuario/logs/wp-errors.log' );
define( 'WP_DEBUG_DISPLAY', false );

Três regras para esse caminho. Use um caminho absoluto — um caminho relativo é resolvido a partir do diretório de trabalho do PHP, que muda de requisição para requisição e de servidor para servidor, então você perde o arquivo de vista. O diretório precisa já existir; o PHP não cria, e se não conseguir abrir o arquivo ele falha em silêncio. E o diretório precisa ter permissão de escrita para o usuário do PHP, que em hospedagem compartilhada não é a mesma conta com que você entra por SFTP.

Se a sua hospedagem te prende dentro da raiz do site e não há onde gravar acima dela, mantenha o caminho padrão e bloqueie o acesso no nível do servidor. No Apache:

<Files "debug.log">
  Require all denied
</Files>

Isso vai num arquivo .htaccess dentro de wp-content, não no da raiz — o WordPress reescreve o .htaccess da raiz quando você salva os links permanentes e pode apagar o que você acrescentou. No nginx, .htaccess não faz nada; você precisa de um bloco location na configuração do servidor, o que em hospedagem gerenciada normalmente significa pedir ao suporte.

Seja honesto sobre o que o bloqueio te dá: o arquivo continua no disco, num diretório que o servidor web serve. Uma falha de travessia de caminho em qualquer plugin ainda consegue lê-lo. Tirar o arquivo da raiz do site é a correção mais forte.

Como ler e acompanhar o arquivo

Via SSH, acompanhe ao vivo enquanto reproduz o problema:

tail -f wp-content/debug.log

Reproduza o erro em outra aba e as linhas novas aparecem conforme são gravadas. Para ver só o que aconteceu há pouco, ou filtrar por um plugin:

tail -n 100 wp-content/debug.log
grep -i 'plugin-slug' wp-content/debug.log | tail -n 50

O PHP acrescenta no fim do arquivo, então leia de baixo para cima. Cada entrada tem data e hora em UTC, que não vai bater com o fuso configurado no seu WordPress — não deixe isso te fazer pensar que está olhando entradas antigas.

Com o WP-CLI dá para alternar as constantes sem editar o arquivo na mão:

wp config set WP_DEBUG true --raw
wp config set WP_DEBUG_LOG true --raw
wp config set WP_DEBUG_DISPLAY false --raw

A flag --raw faz diferença — sem ela, o valor é gravado como a string "true" e não como o booleano. Na forma com caminho, tire o --raw para que seja gravado como string entre aspas.

Sem SSH? Baixe o arquivo por SFTP ou abra no gerenciador de arquivos da hospedagem. Evite plugins que mostram o log dentro do wp-admin, a não ser que você confie neles por completo; você está dando a um plugin acesso de leitura a um arquivo cheio de detalhes internos do servidor.

Se você quer o bloco exato do wp-config para o seu cenário, incluindo um caminho seguro fora da raiz e a regra de servidor correspondente, o gerador de log de depuração do WordPress monta tudo para você.

Desligue quando terminar

Nada no núcleo do WordPress faz rotação ou limpeza do debug.log. Num site que dispara um aviso a cada carregamento de página, ele cresce sem limite e pode lotar o disco — o que derruba o site com muito mais força do que o problema que você estava investigando. Ligue o registro, reproduza o problema, leia o log e devolva o WP_DEBUG para false.

Para esvaziar o arquivo sem apagá-lo:

: > wp-content/debug.log

Quando o log continua vazio

Percorra esta lista em ordem. O WP_DEBUG está como false — de longe a causa mais comum, e ela desliga todo o resto em silêncio. A constante está abaixo da linha do “stop editing” no wp-config.php. Permissões de arquivo — o PHP não consegue gravar em wp-content nem no diretório personalizado que você indicou. Um erro fatal antes do wp-config terminar de carregar, como um erro de sintaxe no próprio arquivo de configuração, acontece cedo demais para o registro do WordPress capturar; esses vão para o log de erros do PHP do servidor. A hospedagem sobrescreve tudo — algumas plataformas gerenciadas fixam a configuração error_log do PHP ou desviam o registro para o painel delas, e nesse caso as suas constantes estão certas e a saída simplesmente está em outro lugar. Confira o visualizador de logs da hospedagem antes de concluir que a sua configuração está errada.