Expressões cron parecem crípticas à primeira vista - cinco campos separados por espaços repletos de asteriscos, números, barras e vírgulas. Mas há uma lógica consistente em cada campo e, uma vez que você a entenda, ler e escrever agendamentos cron se torna simples. Este guia decompõe cada parte da sintaxe cron, explica os caracteres especiais, mostra os padrões de agendamento mais comuns e apresenta as ferramentas que resolvem, validam e simulam expressões cron antes de você implantá-las.
O que é uma expressão cron?
Uma expressão cron é uma cadeia de cinco (ou às vezes seis) campos separados por espaços que define um agendamento recorrente para tarefas automatizadas. O formato foi inventado com o daemon cron do Unix no início dos anos 1970 e permaneceu essencialmente inalterado desde então. Hoje ele é usado em arquivos crontab do Linux, pipelines de CI/CD como GitHub Actions e GitLab CI, agendadores na nuvem como AWS EventBridge e Google Cloud Scheduler, orquestradores de contêineres como Kubernetes CronJob e frameworks de aplicação como Spring e Quartz.
A anatomia de uma expressão cron
O formato padrão de cinco campos é:
┌----------- minuto (0-59)
│ ┌--------- hora (0-23)
│ │ ┌------- dia do mês (1-31)
│ │ │ ┌----- mês (1-12)
│ │ │ │ ┌--- dia da semana (0-7, domingo = 0 ou 7)
│ │ │ │ │
* * * * * comando a executarOs campos são lidos da esquerda para a direita: minuto, hora, dia do mês, mês, dia da semana. A expressão "0 9 * * 1-5" dispara às 09:00 em todos os dias úteis. Cada campo pode conter um valor único, uma lista separada por vírgulas, um intervalo, um passo, um curinga ou uma combinação. Entender esses operadores é toda a habilidade de ler cron.
Note
Sintaxe da expressão cron campo a campo
Cada campo tem um intervalo definido de valores inteiros válidos. Valores fora do intervalo válido produzem um erro ou uma configuração incorreta silenciosa, dependendo da implementação do cron. Entender o intervalo válido de cada campo é a base para ler qualquer expressão cron.
Intervalos válidos dos campos
- Minuto - de 0 a 59. O valor 0 é o início da hora; o valor 59 é um minuto antes da próxima hora.
- Hora - de 0 a 23. Usa formato de 24 horas: 0 é meia-noite, 12 é meio-dia, 23 é 11 PM.
- Dia do mês - de 1 a 31. Os dias são indexados a partir de 1. Alguns meses têm menos dias - fevereiro tem 28 ou 29, e abril/junho/setembro/novembro têm 30.
- Mês - de 1 a 12. Janeiro é 1, dezembro é 12. Algumas implementações também aceitam abreviações de três letras: JAN, FEB, MAR, etc.
- Dia da semana - de 0 a 7. Tanto 0 quanto 7 representam domingo. Segunda é 1, sábado é 6. Algumas implementações suportam MON, TUE, WED, THU, FRI, SAT, SUN.
Como os campos interagem
Os cinco campos são avaliados juntos como um E lógico - a tarefa é executada quando todos os campos sem curinga coincidem simultaneamente. "0 9 15 * *" dispara exatamente às 09:00 no dia 15 de cada mês. A exceção crítica ocorre quando o dia do mês e o dia da semana são ambos valores sem curinga - nesse caso, a maioria dos daemons cron dispara se QUALQUER uma das condições for verdadeira (um OU lógico), não ambas. Essa é uma fonte notória de comportamentos inesperados.
Warning
Caracteres especiais explicados
O poder do cron vem de seus caracteres especiais - os operadores que transformam valores fixos em padrões de agendamento flexíveis. Dominar esses seis operadores cobre praticamente todos os padrões de agendamento que você encontrará.
Os seis operadores principais
| Caractere | Nome | Exemplo | Significado |
|---|---|---|---|
| * | Curinga | * no minuto | Todos os valores válidos (0-59 para minutos) |
| , | Lista | 1,15,30 no minuto | Nos minutos 1, 15 e 30 |
| - | Intervalo | 1-5 no dia da semana | De segunda a sexta (dias 1 a 5) |
| / | Passo | */15 no minuto | A cada 15 minutos (0, 15, 30, 45) |
| ? | Não especificado | ? no dia do mês | Nenhum valor específico (apenas Quartz/Spring) |
| @ | Macro | @daily | Apelidos abreviados (@daily = 0 0 * * *) |
Combinando operadores
Os operadores podem ser combinados dentro de um mesmo campo. "0,30 9-17 * * 1-5" significa "nos minutos 0 e 30 de cada hora das 9h às 17h, de segunda a sexta". A sintaxe de passo também pode ser aplicada a um intervalo: "0-30/5" no campo de minuto significa a cada 5 minutos do minuto 0 ao minuto 30 (0, 5, 10, 15, 20, 25, 30). O Tradutor de Cron para Linguagem Natural decompõe qualquer combinação em linguagem clara com explicações campo a campo.
Tip
Padrões de agendamento cron comuns
A maioria dos agendamentos cron do mundo real se encaixa em um punhado de padrões recorrentes. Conhecer esses padrões de vista permite ler a maioria dos crontabs de produção sem consulta.
- "* * * * *" - A cada minuto. O agendamento mais frequente possível. Usado para verificações de pulso e monitoramento.
- "*/5 * * * *" - A cada 5 minutos. Comum para tarefas de polling e aquecimento de cache.
- "0 * * * *" - A cada hora cheia. Padrão para processos em lote horários.
- "0 0 * * *" - Diariamente à meia-noite (UTC). O padrão para tarefas de limpeza diária.
- "0 9 * * 1-5" - 9h em todos os dias úteis. Agendamento padrão em horário comercial.
- "0 0 1 * *" - Meia-noite no dia 1 de cada mês. Execuções de faturamento mensal, geração de relatórios.
- "0 0 1 1 *" - Meia-noite em 1º de janeiro. Tarefas anuais - renovações de licenças, relatórios de fim de ano.
- "0 0 * * 0" - Meia-noite todo domingo. Janelas de manutenção semanais.
Construindo agendamentos personalizados a partir de padrões
A maioria dos agendamentos complexos são combinações desses padrões. "0 2 * * 6,0" significa "2h aos sábados e domingos" - a janela de manutenção do fim de semana. "*/10 8-18 * * 1-5" significa "a cada 10 minutos das 8h às 18h, somente dias úteis". Se você conhece o agendamento desejado em linguagem clara, o Crontab Expression Builder permite configurar cada campo visualmente e gera a expressão correta com uma confirmação legível e as próximas cinco execuções.
Crontab Expression Builder
Crie expressões cron visualmente com 15 predefinições, 5 modos de campo, descrição instantânea em linguagem clara e pré-visualização das próximas 5 execuções - grátis, sem cadastro.
Como criar e validar expressões cron
Escrever uma expressão cron do zero e torcer para que esteja correta é arriscado. Um único campo transposto ou um operador mal compreendido pode fazer uma tarefa disparar em horários completamente errados - ou nunca disparar. Essas ferramentas eliminam esse risco.
Escreva ou selecione sua expressão
Abra o Crontab Expression Builder e digite sua expressão diretamente ou escolha entre as 15 predefinições integradas. Cada predefinição cobre um padrão de agendamento comum (a cada minuto, horário, diário, dias úteis, mensal) e pode ser ajustada com os controles visuais de campo sem tocar na expressão bruta.
Valide erros de sintaxe
Cole a expressão no Validador de Expressões Cron. Ele verifica cada campo contra seu intervalo válido, valida os limites dos intervalos (o início deve ser menor que o fim), confirma que os valores de passo não são zero e sinaliza macros não suportadas pelo crontab padrão de 5 campos. Cada erro vem com uma mensagem em nível de linha explicando o que o analisador esperava.
Traduza para linguagem clara
Passe a expressão validada pelo Tradutor de Cron para Linguagem Natural. A saída é uma frase completa em linguagem clara descrevendo o agendamento - "Às 2h30, nas segundas, quartas e sextas" - além de uma decomposição campo a campo. Se a descrição não corresponder à sua intenção, revise a expressão antes de implantar.
Simule os próximos 12 meses de execuções
Para tarefas agendadas em que o momento importa - execuções de faturamento, exportações de dados, janelas de manutenção - abra o Interactive Cron Scheduler e simule a expressão pelos próximos 12 meses. A visão de calendário mostra a densidade mensal de execuções e a linha do tempo mostra carimbos de data/hora exatos. Confirme que o agendamento dispara nas datas esperadas antes de mesclar a configuração em produção.
Validador de Expressões Cron
Valide sintaxe cron de 5 campos, intervalos, passos, valores de lista e macros com diagnósticos instantâneos por campo - local no navegador, grátis, sem cadastro.
Cron em CI/CD e agendadores na nuvem
A sintaxe cron é usada muito além do crontab do Linux. As plataformas modernas de CI/CD e nuvem adotaram o mesmo formato de 5 campos, mas cada uma tem suas peculiaridades no tratamento de fuso horário, suporte a macros e restrições de intervalo mínimo.
Diferenças plataforma por plataforma
| Plataforma | Campos | Fuso horário | Macros | Intervalo mín. |
|---|---|---|---|---|
| Linux crontab | 5 | Local do sistema | ✓ Todas as 6 | A cada minuto |
| GitHub Actions | 5 | Somente UTC | ✗ Nenhuma | A cada 5 min (deriva forçada de 15 min) |
| GitLab CI | 5 | Somente UTC | ✓ Parcial | A cada minuto |
| AWS EventBridge | 5 ou 6 | Somente UTC | ✗ Nenhuma | A cada minuto |
| Google Cloud Scheduler | 5 ou unix | Qualquer fuso IANA | ✓ Algumas | A cada minuto |
| Kubernetes CronJob | 5 | Fuso do cluster | ✗ Nenhuma | A cada minuto |
| Spring Scheduler | 6 | Padrão da JVM | ✓ Sim | A cada segundo |
Agendamento cron no GitHub Actions
O GitHub Actions usa a sintaxe cron padrão de 5 campos, mas sempre executa em UTC. Se você quer uma tarefa às 9h no horário do Leste (UTC-5), escreve "0 14 * * *". O GitHub Actions também não suporta sintaxe de macros (@daily, @weekly), então use a expressão completa. Workflows agendados durante períodos de alta carga podem disparar com até 15 minutos de atraso - projete suas tarefas para tolerar essa deriva.
Convertendo cron para temporizadores systemd
Os sistemas Linux modernos usam cada vez mais temporizadores systemd em vez do crontab clássico. O formato OnCalendar do systemd usa uma sintaxe diferente, mas cobre os mesmos padrões. O Conversor de Cron para Temporizador Systemd converte qualquer expressão cron de 5 campos em sua configuração equivalente de unidade de temporizador systemd, incluindo um modelo completo de arquivos .timer e .service.
Armadilhas e casos extremos do cron
Até desenvolvedores experientes encontram falhas silenciosas com o cron. Estas são as armadilhas mais comuns - cada uma já custou a sistemas de produção indisponibilidade despercebida ou execuções duplicadas de tarefas.
Surpresas de fuso horário
O cron executa no fuso horário local do servidor por padrão. Se o seu servidor está em UTC mas o seu negócio está em Nova York (UTC-5), "0 9 * * *" dispara às 4h no horário local, não às 9h. Plataformas na nuvem como GitHub Actions e AWS EventBridge sempre executam em UTC, o que significa que toda a matemática de fuso horário recai sobre você. Confirme sempre o fuso horário antes de implantar um agendamento. O Interactive Cron Scheduler permite simular execuções com o deslocamento de fuso aplicado.
Casos extremos de fim de mês
Agendar uma tarefa no dia 29, 30 ou 31 do mês faz com que ela salte silenciosamente os meses que não têm essa data. "0 0 31 * *" nunca executa em abril, junho, setembro ou novembro. "0 0 29 2 *" executa em fevereiro somente em anos bissextos. Se você precisa de um agendamento de "último dia do mês", é preciso uma abordagem mais inteligente - ou executar diariamente com um script que verifica a data, ou usar um agendador na nuvem que suporte a sintaxe L (último) dia.
Transições de horário de verão
As transições do horário de verão podem fazer tarefas cron executarem duas vezes ou serem puladas. Quando os relógios adiantam, os horários dentro da hora pulada nunca ocorrem. Quando os relógios atrasam, os horários dentro da hora repetida ocorrem duas vezes. Tarefas agendadas em um fuso horário local durante a janela de transição são afetadas. A prática mais segura é executar servidores e agendadores em UTC, que nunca tem transições de horário de verão.
Warning
O problema do cada segundo
O cron padrão de 5 campos tem uma resolução mínima de um minuto. Se você precisa de uma tarefa a cada 10 segundos, o cron não é a ferramenta certa - use um temporizador do sistema, uma fila de tarefas com atrasos ou o campo de segundos disponível no Spring Scheduler e no Quartz. Tentar aproximar agendamentos sub-minuto com várias entradas de crontab é propenso a erros e cria condições de corrida quando as tarefas se sobrepõem.
Key takeaways
- Uma expressão cron tem cinco campos: minuto (0-59), hora (0-23), dia do mês (1-31), mês (1-12), dia da semana (0-7).
- Os seis caracteres especiais são * (curinga), , (lista), - (intervalo), / (passo), ? (não especificado, apenas Quartz) e @ (macros como @daily).
- Quando o dia do mês e o dia da semana são ambos sem curinga, a maioria dos daemons cron dispara se QUALQUER um coincidir - uma fonte comum de execuções duplas inesperadas.
- Use o Crontab Expression Builder para construir visualmente, o Validador de Expressões Cron para verificar a sintaxe e o Interactive Cron Scheduler para simular 12 meses de execuções.
- O GitHub Actions usa cron de 5 campos somente UTC sem suporte a macros; AWS EventBridge e Google Cloud Scheduler também usam UTC; o crontab do Linux usa o fuso horário local do sistema.
- Não agende no dia 29, 30 ou 31 se precisar que a tarefa execute todo mês - esses dias não existem em todos os meses.
- O cron padrão tem resolução mínima de um minuto; use temporizadores systemd, filas de tarefas ou Spring/Quartz para necessidades de agendamento sub-minuto.