Resposta rápida
Se o Cron Trigger do seu Cloudflare Worker não executa como esperado, inicie o ambiente local com cf dev, wrangler dev ou o plugin da Cloudflare para Vite e abra /cdn-cgi/local/explorer. Selecione o Worker, entre em Cron Triggers e dispare a expressão configurada ou uma expressão ad hoc. O resultado mostra a expressão enviada, o horário simulado, o outcome e o estado de noRetry().
O teste pelo Local Explorer exige Wrangler 4.139.0 ou posterior, ou Cloudflare Vite plugin 1.60.0 ou posterior, e o Worker precisa exportar um handler scheduled(). A execução é local e única: ela não cria, altera nem executa automaticamente o agendamento implantado em produção.
O que mudou em 17 de outubro de 2026
A Cloudflare adicionou ao Local Explorer uma interface própria para Cron Triggers. Antes, o diagnóstico local dependia principalmente de construir uma URL de teste ou chamar a rota de scheduled por HTTP. Agora é possível disparar expressões configuradas, montar expressões temporárias, salvar horários de teste no navegador e inspecionar o resultado na mesma interface.
A mudança também expõe a operação pela API do Local Explorer. Ferramentas e agentes podem ler a especificação OpenAPI da sessão local e enviar uma invocação para um Worker específico, com a expressão cron e um horário opcional. Isso ajuda a reproduzir uma falha, mas não dá ao agente autorização automática para implantar ou modificar recursos remotos.
Confirme os requisitos antes de testar
A opção pode não aparecer quando a ferramenta local está desatualizada. Confira a versão do Wrangler ou do plugin Vite usado pela sessão, reinicie o servidor depois da atualização e confirme que o projeto realmente exporta scheduled(). Para testar uma expressão configurada, ela precisa existir no ambiente ativo; uma expressão ad hoc pode ser usada sem editar a configuração.
O Local Explorer fica no servidor de desenvolvimento. Em uma sessão padrão do Wrangler, abra a URL exibida no terminal e acrescente /cdn-cgi/local/explorer. Não presuma a porta 8787: o Vite costuma usar 5173 e projetos com várias aplicações podem escolher outra porta.
- Atualize para Wrangler 4.139.0 ou posterior, ou Vite plugin 1.60.0 ou posterior.
- Confirme que o módulo exporta async scheduled(controller, env, ctx).
- Inicie o projeto com cf dev, wrangler dev ou o plugin Vite.
- Abra a URL local informada pelo servidor e acesse /cdn-cgi/local/explorer.
- Selecione o Worker correto antes de abrir Cron Triggers.
Teste uma expressão configurada
Em Cron Triggers, abra Configured Crons. Escolha Now para usar o horário atual ou adicione um preset com data e hora UTC ou epoch em milissegundos. Dispare a expressão e confira outcome, noRetry(), expressão e horário agendado. Se houver mais de uma expressão, teste cada caminho porque o código pode usar controller.cron para decidir qual tarefa executar.
A comparação de controller.cron é literal. Espaços e a forma exata da expressão importam quando o handler usa um switch. Um teste que envia uma expressão equivalente, mas escrita de outro modo, pode seguir um ramo diferente ou não entrar em nenhum caso. Use no Local Explorer o mesmo texto que está na configuração quando quiser reproduzir o comportamento implantado.
- Abra Cron Triggers e depois Configured Crons.
- Escolha Now ou informe um horário UTC que reproduza o caso.
- Dispare uma expressão por vez.
- Confira outcome, noRetry, cron e scheduled time.
- Abra logs e traces da mesma invocação para localizar a operação que falhou.
Use um trigger ad hoc sem alterar produção
Ad-Hoc Triggers permite informar uma expressão exata ou usar o construtor para intervalos comuns, dias selecionados e opções como último dia ou dia útil mais próximo. A expressão mostrada na linha é a que será enviada ao handler. Use essa área para testar uma hipótese sem adicionar o cron ao arquivo de configuração.
As expressões ad hoc e os presets de horário ficam no navegador e são associados ao projeto e ao Worker local. Eles não modificam cloudflare.config.ts, wrangler.jsonc, wrangler.toml nem os Cron Triggers implantados. Fechar o servidor ou guardar um preset também não transforma o teste em um agendamento recorrente.
Atenção ao horário do Brasil
Cron Triggers usam UTC. O runtime local do Wrangler também opera com TZ=UTC para se aproximar da produção, mesmo quando o computador está no horário de Brasília. Uma rotina esperada para 09:00 em Brasília corresponde a 12:00 UTC durante o período sem horário de verão; trate essa conversão explicitamente e não dependa do fuso configurado na máquina.
Para reproduzir uma data sensível, informe no preset o instante UTC correto ou use epoch em milissegundos. Dentro do handler, controller.scheduledTime representa o horário agendado em milissegundos desde 1º de janeiro de 1970 UTC. Converta esse valor de forma controlada nos testes e registre o instante junto com a expressão recebida.
Leia logs e traces da invocação correta
O Local Explorer captura logs e traces das invocações locais. Os logs mostram console.error, console.warn e outras saídas; os traces detalham operações em bindings, duração, status e erro. A sessão de desenvolvimento que possui o Worker precisa estar com Observability ativada para fornecer o conjunto completo descrito pela documentação.
Use um identificador de correlação para cada execução e evite registrar tokens, payloads pessoais ou segredos. Quando o handler chama D1, KV, R2, Durable Objects ou uma API externa, confirme no trace qual etapa iniciou e qual falhou. Um outcome genérico sem o trace pode esconder que o handler abriu corretamente, mas a segunda operação não concluiu.
Teste por HTTP, API ou agente
Para um teste scriptado, a rota /cdn-cgi/local/scheduled continua disponível no servidor local. Acrescente format=json para receber o resultado estruturado. O comando deve usar a porta real da sessão e pode enviar parâmetros de cron e horário conforme a documentação atual.
A API do Local Explorer fica em /cdn-cgi/local/explorer/api. Ela publica uma especificação OpenAPI e oferece POST /local/scheduled com o nome exato do Worker. Um agente pode descobrir a operação, disparar um caso e consultar traces, mas limite o acesso à máquina de desenvolvimento e revise o que o agente pode ler ou alterar nos bindings locais.
- Para um teste simples, chame /cdn-cgi/local/scheduled?format=json.
- Para atingir um Worker específico, use a API do Local Explorer e informe o nome exato.
- Envie a expressão cron e, quando necessário, o scheduled_time em epoch.
- Relacione a resposta ao trace e aos logs da mesma sessão.
- Nunca exponha o servidor local ou seus bindings sem autenticação e necessidade comprovada.
Por que funciona localmente e falha em produção
Um teste local aprovado confirma o comportamento do código para a expressão e o horário enviados; não prova que o trigger foi implantado. Em produção, confira se o cron existe no ambiente correto, se o deploy usou a configuração esperada e se a alteração já propagou. A Cloudflare informa que mudanças em Cron Triggers podem levar até 15 minutos para alcançar a rede global.
Também compare bindings, variáveis, secrets, permissões e conectividade externa entre local e produção. Eventos recentes podem demorar a aparecer em algumas visões do painel, e uma falha ampla deve ser separada de um erro do handler consultando o Cloudflare Status antes de remover o agendamento ou repetir operações com efeito externo.
- Confirme o ambiente e o arquivo de configuração usados no deploy.
- Verifique se a expressão implantada corresponde exatamente à expressão testada.
- Aguarde a janela de propagação documentada após criar ou alterar o trigger.
- Compare secrets, bindings e endpoints entre local e produção.
- Consulte eventos, logs, traces e o Cloudflare Status no mesmo intervalo UTC.
Limitações e próxima ação útil
Este guia foi verificado em 18 de outubro de 2026. Cada clique no Local Explorer produz uma invocação local única; o ambiente não espera o próximo horário da expressão e não executa a agenda automaticamente. O teste pode usar recursos locais ou bindings remotos conforme a configuração, portanto revise o risco antes de disparar e não trate dados de produção como massa de teste.
Escolha uma rotina sem efeito financeiro ou destrutivo, teste o mesmo cron em três horários UTC e force uma falha controlada em um binding. Confirme outcome, noRetry, logs e trace e depois compare a configuração implantada. Quando esse fluxo estiver reproduzível, automatize apenas os casos seguros pela API local e mantenha a implantação como etapa separada e revisada.
Faça o próximo teste
Fontes consultadas
Os links abaixo servem para conferir conceitos, orientações oficiais e o critério editorial usado neste conteúdo.
- Test Cron Triggers with Local ExplorerCloudflare Changelog
- Local ExplorerCloudflare Docs
- Cron TriggersCloudflare Docs
- Scheduled HandlerCloudflare Docs
- Wrangler dev commandCloudflare Docs
- Cloudflare StatusCloudflare