Configurar WP-Cron no WordPress: diagnóstico e ajuste fino

15 min de leitura  ·  Guia técnico

Configurar WP-Cron no WordPress significa substituir ou ajustar o sistema de agendamento nativo do CMS para garantir que tarefas como backups, publicações programadas e renovação de cache executem no horário correto. Para configurar e otimizar o WP-Cron, siga estes passos:

1. Diagnostique o estado atual do WP-Cron com WP-CLI ou o plugin WP Crontrol.
2. Ative o modo de depuração no wp-config.php para identificar erros silenciosos.
3. Desative o WP-Cron nativo adicionando DISABLE_WP_CRON no wp-config.php.
4. Crie uma entrada no crontab do servidor para chamar o WP-Cron a cada 5 minutos.
5. Valide a execução verificando logs e listando eventos agendados via WP-CLI.

Pré-requisitos para configurar o WP-Cron corretamente

• Acesso SSH ao servidor (VPS, servidor dedicado ou hospedagem com shell habilitado).
• WordPress 6.x instalado e funcional.
• WP-CLI instalado no servidor (versão 2.8 ou superior recomendada).
• PHP 8.1 ou superior configurado como interpretador padrão.
• Permissão para editar o arquivo wp-config.php via SSH ou FTP.
• Acesso ao crontab do usuário do sistema operacional (Linux com cron daemon ativo).
• Plugin WP Crontrol instalado no painel WordPress (opcional, mas recomendado para diagnóstico visual).

Diagnóstico completo do WP-Cron no WordPress

O agendamento de tarefas no WordPress depende de um mecanismo chamado WP-Cron, que é acionado a cada requisição HTTP recebida pelo site. Antes de qualquer ajuste, é essencial entender o estado atual dos eventos agendados e identificar falhas silenciosas que podem estar causando atrasos em publicações, backups ou envios de e-mail.

Verificar eventos agendados com WP-CLI

Conecte-se ao servidor via SSH e navegue até o diretório raiz da instalação WordPress. Em seguida, execute:

wp cron event list --path=/var/www/html/seusite

Ao rodar este comando, você verá uma saída semelhante a esta:

+----------------------------+---------------------+----------+
| hook                       | next_run_gmt        | schedule |
+----------------------------+---------------------+----------+
| wp_scheduled_delete        | 2024-06-01 03:00:00 | daily    |
| wp_update_themes           | 2024-06-01 12:00:00 | twicedaily|
| wp_version_check           | 2024-06-01 06:00:00 | twicedaily|
+----------------------------+---------------------+----------+

Se a coluna next_run_gmt mostrar horários muito defasados em relação ao horário atual, o WP-Cron não está sendo acionado com regularidade — sinal claro de que o site tem pouco tráfego ou que o mecanismo está bloqueado.

Configurar WP_DEBUG para capturar erros do WP-Cron

Erros em callbacks de eventos agendados são silenciosos por padrão. Para expô-los, edite o wp-config.php:

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

Os erros serão gravados em wp-content/debug.log. Monitore o arquivo com:

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

Procure por entradas relacionadas a wp-cron.php, callbacks de plugins ou erros de banco de dados que possam estar interrompendo a fila de tarefas.

Verificar se o WP-Cron está bloqueado por firewall ou configuração de servidor

O WP-Cron nativo faz uma requisição HTTP interna para wp-cron.php. Se o servidor bloquear requisições de loopback, o cron nunca executará. Teste manualmente:

curl -I https://seusite.com.br/wp-cron.php?doing_wp_cron

HTTP/2 200
content-type: text/html; charset=UTF-8

Se o retorno for 403, 500 ou timeout, há um bloqueio ativo — verifique regras de firewall (UFW, iptables) ou configurações de segurança do Nginx/Apache que possam estar rejeitando requisições internas.

Como desativar o WP-Cron nativo e usar o cron do Linux

A substituição do WP-Cron pelo cron real do sistema operacional é a abordagem recomendada para sites em produção. Isso elimina o overhead de verificação a cada requisição e garante execução pontual independente do volume de tráfego.

Desativar o WP-Cron no wp-config.php

Atenção: edite o wp-config.php com cuidado. Um erro de sintaxe neste arquivo derruba o site inteiro. Faça backup antes de prosseguir.

Abra o arquivo com seu editor preferido:

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

Adicione a linha abaixo antes do comentário /* That's all, stop editing! */:

define( "DISABLE_WP_CRON", true );

Salve e feche o arquivo. A partir deste momento, o WordPress não tentará mais acionar o cron via requisições HTTP internas.

Criar entrada no crontab do servidor

Acesse o crontab do usuário que executa o PHP (geralmente www-data no Debian/Ubuntu ou apache no AlmaLinux 9):

crontab -u www-data -e

Adicione a seguinte linha para executar o WP-Cron a cada 5 minutos usando WP-CLI:

*/5 * * * * /usr/local/bin/wp cron event run --due-now --path=/var/www/html/seusite --quiet

Alternativamente, se preferir usar curl em vez de WP-CLI:

*/5 * * * * curl -s -o /dev/null https://seusite.com.br/wp-cron.php?doing_wp_cron

A opção com WP-CLI é preferível porque não depende de conectividade HTTP e executa diretamente no contexto PHP do servidor, evitando problemas com certificados SSL ou redirecionamentos.

Verificar se o crontab está ativo

Após salvar, confirme que o daemon cron está rodando:

systemctl status cron

● cron.service - Regular background program processing daemon
     Loaded: loaded (/lib/systemd/system/cron.service; enabled)
     Active: active (running) since Sat 2024-06-01 00:00:01 UTC

No AlmaLinux 9 ou Rocky Linux 9, o serviço pode se chamar crond:

systemctl status crond

Ajuste fino: intervalos personalizados e eventos customizados

O WordPress oferece intervalos padrão como hourly, twicedaily e daily, mas plugins frequentemente registram intervalos customizados. O ajuste fino do agendamento de tarefas permite otimizar o consumo de recursos e evitar picos de processamento simultâneos.

Listar e forçar execução de eventos específicos

Para executar um evento específico manualmente e validar seu funcionamento:

wp cron event run wp_scheduled_delete --path=/var/www/html/seusite

Success: Executed the cron event 'wp_scheduled_delete'.

Registrar intervalos personalizados via functions.php

Se um plugin ou tema precisar de um intervalo não disponível nativamente, adicione ao functions.php do tema filho:

add_filter( 'cron_schedules', function( $schedules ) {
    $schedules['every_five_minutes'] = array(
        'interval' => 300,
        'display'  => 'A cada 5 minutos',
    );
    return $schedules;
} );

Este intervalo ficará disponível para qualquer plugin que use wp_schedule_event(). Lembre-se de que intervalos muito curtos (menos de 1 minuto) não fazem sentido quando o cron do sistema é configurado para rodar a cada 5 minutos.

Monitorar o histórico de execução com WP Crontrol

O plugin WP Crontrol (disponível no repositório oficial do WordPress) oferece uma interface visual para listar, editar, pausar e executar manualmente qualquer evento agendado. Após instalá-lo, acesse Ferramentas > Cron Events no painel administrativo. Você verá o próximo horário de execução de cada hook, o intervalo configurado e o callback associado.

Para sites hospedados em planos compartilhados onde o acesso SSH é limitado, o WP Crontrol é a principal ferramenta de diagnóstico disponível. Veja também o artigo Comparativo: Hospedagem de sites vs. VPS: qual é a melhor opção? para entender quando migrar para um ambiente com mais controle sobre o agendamento de tarefas.

Impacto do WP-Cron na performance do WordPress

O overhead gerado pelo WP-Cron nativo é frequentemente subestimado. A cada requisição ao site, o WordPress executa a função wp_cron(), que consulta o banco de dados para verificar se há tarefas pendentes. Em sites com alto volume de acessos, isso representa centenas de consultas extras por minuto ao MySQL ou MariaDB.

Medir o impacto no TTFB antes e depois da mudança

Antes de desativar o WP-Cron nativo, registre o TTFB (Time to First Byte) médio do site usando ferramentas como curl:

curl -o /dev/null -s -w "TTFB: %{time_starttransfer}s\n" https://seusite.com.br/

TTFB: 0.342s

Após configurar o cron do sistema e desativar o WP-Cron nativo, repita a medição. Em sites com tráfego moderado a alto, reduções de 20 a 80 milissegundos no TTFB são comuns, especialmente quando há muitos plugins com eventos agendados registrados.

Plugins que sobrecarregam o WP-Cron

Alguns plugins registram dezenas de eventos agendados sem limpeza adequada. Para identificar acúmulo de eventos:

wp cron event list --path=/var/www/html/seusite | wc -l

Se o número de eventos for superior a 50, investigue quais plugins estão registrando hooks em excesso. Plugins de backup, SEO e cache são os principais candidatos. Considere revisar as configurações de agendamento de cada um ou substituí-los por alternativas mais eficientes.

Para otimizações mais amplas no servidor, consulte as Dicas de Otimização de Servidores Linux disponíveis na base de conhecimento da AviraHost.

Problemas comuns e como resolver

Sintoma: eventos agendados nunca executam em sites com pouco tráfego

Causa: o WP-Cron nativo depende de requisições HTTP para ser acionado. Sites com menos de uma visita por hora podem ter tarefas atrasadas por horas ou dias.
Solução: desative o WP-Cron nativo com DISABLE_WP_CRON e configure o cron do sistema operacional para chamar o WP-Cron a cada 5 minutos, conforme descrito na seção anterior. Isso garante execução pontual independente do tráfego.

Sintoma: erro "doing_wp_cron" travado no banco de dados

Causa: quando o WP-Cron inicia uma execução e o processo é interrompido (timeout de PHP, erro fatal), o lock doing_cron pode ficar registrado na tabela wp_options, impedindo novas execuções.
Solução: remova o lock manualmente via WP-CLI:

wp option delete doing_cron --path=/var/www/html/seusite

Em seguida, aumente o max_execution_time do PHP no php.ini ou no .htaccess para evitar timeouts durante tarefas longas:

php_value max_execution_time 300

Sintoma: crontab configurado mas eventos ainda não executam

Causa: o caminho do WP-CLI ou do PHP no crontab está incorreto, ou o usuário do crontab não tem permissão de leitura nos arquivos do WordPress.
Solução: verifique o caminho absoluto do WP-CLI:

which wp

/usr/local/bin/wp

Confirme que o usuário do crontab tem permissão de leitura no diretório WordPress:

ls -la /var/www/html/seusite/wp-config.php

Se necessário, ajuste as permissões ou execute o crontab com o usuário correto. Adicione redirecionamento de saída para um log temporário para depurar:

*/5 * * * * /usr/local/bin/wp cron event run --due-now --path=/var/www/html/seusite >> /tmp/wpcron.log 2>&1

Sintoma: publicações agendadas não são publicadas no horário

Causa: o fuso horário configurado no WordPress (Configurações > Geral) está diferente do fuso horário do servidor Linux, causando discrepância nos horários de execução.
Solução: verifique o fuso horário do servidor:

timedatectl

Time zone: America/Sao_Paulo (BRT, -0300)

Certifique-se de que o WordPress também está configurado para America/Sao_Paulo em Configurações > Geral > Fuso horário. O WP-Cron armazena horários em UTC internamente, mas a interface do WordPress converte para o fuso configurado — inconsistências aqui causam atrasos aparentes.

Perguntas frequentes sobre WP-Cron no WordPress

O WP-Cron do WordPress é confiável para tarefas agendadas críticas?

O WP-Cron nativo do WordPress não é um daemon real: ele só dispara quando há uma requisição HTTP ao site. Em sites com pouco tráfego, tarefas agendadas podem atrasar horas ou nunca executar. Para tarefas críticas como backups e envio de emails, substitua pelo cron real do sistema operacional, conforme detalhado neste artigo.

Como verificar se o WP-Cron está funcionando corretamente?

Instale o plugin WP Crontrol ou execute via WP-CLI o comando wp cron event list para listar todos os eventos agendados e seus próximos horários de execução. Você também pode verificar o log de erros do PHP em wp-content/debug.log ativando WP_DEBUG no wp-config.php. Compare os horários listados com o horário atual do servidor para identificar eventos atrasados.

Como desativar o WP-Cron nativo e usar o cron do Linux?

Adicione a linha define("DISABLE_WP_CRON", true); no arquivo wp-config.php antes do comentário /* That's all, stop editing! */. Em seguida, crie uma entrada no crontab do servidor apontando para a URL wp-cron.php ou usando WP-CLI com wp cron event run --due-now. Essa combinação garante execução pontual e elimina o overhead de verificação a cada requisição.

Com que frequência devo configurar o cron do sistema para chamar o WP-Cron?

O intervalo recomendado é a cada 5 minutos, o que garante que tarefas agendadas pelo WordPress sejam executadas com precisão aceitável. Intervalos maiores que 15 minutos podem causar atrasos perceptíveis em funcionalidades como publicação agendada de posts e renovação de cache. Para a maioria dos sites, */5 * * * * no crontab é o ponto de equilíbrio ideal entre precisão e consumo de recursos.

O WP-Cron afeta a performance do WordPress?

Sim. A cada requisição ao site, o WordPress verifica se há tarefas pendentes no WP-Cron, o que adiciona overhead de processamento e uma consulta ao banco de dados. Em sites de alto tráfego, isso pode gerar centenas de verificações por minuto. Desativar o WP-Cron nativo e usar o cron do sistema elimina esse overhead e pode melhorar o TTFB de forma mensurável, especialmente em instalações com muitos plugins que registram eventos agendados.

Conclusão

• Diagnostique antes de agir: use wp cron event list e o plugin WP Crontrol para mapear todos os eventos agendados e identificar atrasos antes de fazer qualquer alteração no wp-config.php.
• Substitua o WP-Cron nativo pelo cron do sistema: adicione DISABLE_WP_CRON no wp-config.php e configure o crontab para executar wp cron event run --due-now a cada 5 minutos — essa mudança melhora confiabilidade e performance simultaneamente.
• Monitore continuamente: redirecione a saída do crontab para um arquivo de log temporário durante os primeiros dias após a mudança e verifique se todos os eventos críticos (backups, publicações, emails) estão executando nos horários esperados.

Leia também

• Guia para resolver erro de memória no WordPress: diagnóstico e ampliação
• Solucionar erro 500 no WordPress: diagnóstico rápido e correção definitiva
• Migrar WordPress entre hospedagens sem downtime: procedimento completo

Precisa de ajuda com WordPress e agendamento de tarefas?

Configurar o WP-Cron corretamente pode exigir acesso SSH, edição de arquivos de configuração e conhecimento do ambiente de servidor. Em planos de hospedagem gerenciada da AviraHost, você conta com suporte técnico especializado para ajustar o ambiente PHP, configurar crontabs e garantir que seu WordPress funcione com máxima confiabilidade.

Conheça os planos de hospedagem WordPress da AviraHost