O cron é o agendador de tarefas dos sistemas Unix, e a sua sintaxe infiltrou-se em todo o lado: servidores Linux, Kubernetes, GitHub Actions, funções serverless, Laravel, Spring… Aprendê-la demora dez minutos. Esquecê-la, ainda menos. Este guia foi pensado para ter sempre à mão.
Os cinco campos
Uma expressão cron clássica tem cinco campos separados por espaços:
┌───────────── minuto (0–59)
│ ┌─────────── hora (0–23)
│ │ ┌───────── dia do mês (1–31)
│ │ │ ┌─────── mês (1–12 ou JAN–DEC)
│ │ │ │ ┌───── dia da semana (0–7 ou SUN–SAT; 0 e 7 são domingo)
│ │ │ │ │
* * * * * comando
Cada campo aceita estes operadores:
| Símbolo | Significa | Exemplo | Lê-se |
|---|---|---|---|
* |
qualquer valor | * * * * * |
a cada minuto |
, |
lista | 0 9,14 * * * |
às 9:00 e às 14:00 |
- |
intervalo | 0 9-17 * * * |
a cada hora certa, das 9 às 17 h |
/ |
passo | */15 * * * * |
a cada 15 minutos |
20 exemplos de que vais precisar
| Expressão | Quando corre |
|---|---|
* * * * * |
A cada minuto |
*/5 * * * * |
A cada 5 minutos |
*/15 * * * * |
A cada 15 minutos (:00, :15, :30, :45) |
0 * * * * |
A cada hora, em ponto |
30 * * * * |
A cada hora, e meia |
0 */2 * * * |
A cada 2 horas |
0 0 * * * |
Todos os dias à meia-noite |
0 8 * * * |
Todos os dias às 8:00 |
30 23 * * * |
Todos os dias às 23:30 |
0 9 * * 1-5 |
De segunda a sexta às 9:00 |
0 10 * * 6,0 |
Sábados e domingos às 10:00 |
0 9-18 * * 1-5 |
A cada hora das 9 às 18, em dias úteis |
0 0 * * 0 |
Todos os domingos à meia-noite |
0 0 1 * * |
No dia 1 de cada mês |
0 0 15 * * |
No dia 15 de cada mês |
0 0 1 1 * |
A 1 de janeiro (uma vez por ano) |
0 0 1 */3 * |
No primeiro dia de cada trimestre |
0 3 * * 1 |
Às segundas às 3:00 (clássico para backups) |
*/10 8-20 * * * |
A cada 10 minutos entre as 8:00 e as 20:59 |
0 12 1-7 * 1 |
⚠️ Não é «a primeira segunda-feira do mês» (ver abaixo) |
Se tiveres dúvidas com uma expressão, cola-a no analisador de cron: mostra as próximas datas em que vai correr. E se preferires construí-la sem escrever a sintaxe, o gerador de cron fá-lo com seletores e explica-a em linguagem natural.
Os atalhos com @
O cron do Linux (e a maioria dos seus derivados) aceita aliases legíveis; o GitHub Actions e outros agendadores na nuvem, não:
| Alias | Equivale a |
|---|---|
@yearly ou @annually |
0 0 1 1 * |
@monthly |
0 0 1 * * |
@weekly |
0 0 * * 0 |
@daily ou @midnight |
0 0 * * * |
@hourly |
0 * * * * |
@reboot |
Ao arrancar o sistema |
Os 5 erros que mais tarefas estragam
1. Dia do mês e dia da semana combinam-se com «OU», não com «E»
É a armadilha mais famosa. No cron clássico, se restringires ao mesmo tempo o dia do mês e o dia da semana, a tarefa corre quando se cumprir qualquer um dos dois. Assim, 0 12 1-7 * 1 não significa «a primeira segunda-feira do mês ao meio-dia», mas sim «os dias 1 a 7 de cada mês e também todas as segundas-feiras».
A solução habitual é deixar só um dos dois campos e filtrar no próprio comando:
0 12 1-7 * * [ "$(date +\%u)" = 1 ] && /caminho/script.sh
(Num crontab, o % tem de ser escapado como \%: sem a barra, o cron interpreta-o como uma quebra de linha.)
2. O fuso horário não é o que pensas
O cron usa o fuso horário do sistema onde corre. Num servidor configurado em UTC, 0 9 * * * corre às 9:00 UTC, que em Lisboa são as 9:00 no inverno e as 10:00 no verão. Os agendadores geridos costumam usar UTC: o GitHub Actions usa sempre UTC, e os CronJob do Kubernetes usam o fuso do controlador, a menos que indiques timeZone na especificação.
3. A mudança da hora
Se agendares algo entre a 1:00 e as 2:00 da madrugada em Portugal, no dia da mudança da hora pode ser saltado (na primavera essa hora não existe) ou, conforme a implementação, correr duas vezes (no outono repete-se). Para tarefas críticas, evita essa janela ou trabalha em UTC.
4. Os passos não atravessam a hora
*/7 * * * * não corre «a cada 7 minutos» em sentido estrito: corre nos minutos 0, 7, 14… 56, e na hora seguinte volta a começar no 0. Entre o minuto 56 e o 0 só passam 4 minutos. Para intervalos que não dividem 60, o cron não é a ferramenta certa.
5. Cinco campos ou seis
O cron clássico tem cinco campos e resolução de um minuto. Quartz, Spring (@Scheduled) e bibliotecas como node-cron acrescentam um sexto campo no início para os segundos: 0 */5 * * * * é «a cada 5 minutos» no Spring, mas uma expressão inválida num crontab. Quando copiares uma expressão de um sistema para outro, conta os campos.
Como verificar uma expressão antes do deploy
O método mais fiável é ver as próximas execuções reais. Cola a expressão no analisador de cron, escolhe 5 ou 6 campos conforme o teu sistema e revê a lista de datas: se a tua «primeira segunda-feira do mês» também corre no dia 3, caíste no erro número 1. Tudo é calculado no teu browser, por isso podes testar quantas expressões quiseres.