Cron表达式基于用户本地时间解析,而非UTC时间。这是Claude Code Cron设计中的一个关键决策,意味着当你创建一个Cron任务时,表达式中的时间值(如"每天早上9点")参考的是你当前系统设置的时区,而不是格林威治标准时间。
时区从系统设置自动获取。Claude Code会读取操作系统当前的时区配置——在Linux/macOS中通过 /etc/localtime 或 TZ 环境变量确定,在Windows中通过系统时区设置确定。这一过程对用户透明,无需手动配置。
与UTC的区别和影响:如果采用UTC作为基准,一个配置为"0 9 * * *"的任务会在UTC时间9:00执行,换算到东八区就是下午17:00,这显然不符合中国用户的预期。Claude Code选择本地时间机制,使得"0 9 * * *"在本地就是上午9:00执行,与用户的直觉一致。
为什么设计为本地时间而非UTC:对于个人用户而言,绝大多数Cron任务都与本地生活节奏相关——早上推送日报、晚上执行备份、午间发送提醒等。如果强制使用UTC,用户需要额外进行时区换算,增加了心智负担和出错的概率。本地时间机制让Cron表达式的编写更加直观和自然。
春季时钟拨快1小时:某些时间点不会被执行。当夏令时开始时,凌晨2:00会直接跳到3:00,这意味着原本安排在2:00到3:00之间的所有Cron任务在这一天都会被跳过(never executed)。例如一个配置为"0 2 * * *"的任务,在春季夏令时切换日不会被执行。
秋季时钟拨慢1小时:某些时间点被执行两次。当夏令时结束时,凌晨3:00会回退到2:00,这意味着2:00到3:00之间的时间会经历两次。配置在这一小时内的Cron任务会执行两次(executed twice)——一次在夏令时结束前的第一次2:00,另一次在回退后的第二次2:00。
关键业务任务在DST切换日的处理策略:对于涉及金融交易、数据统计、定期报告等关键任务,建议在DST切换前后增加手动检查。可以在任务逻辑中加入幂等性处理(idempotency),确保即使任务被跳过或重复执行,也不会产生数据错误或重复操作。
避免在凌晨2-3点安排关键任务:如果业务允许,最直接的解决方案是将关键Cron任务安排在DST切换窗口之外的时间段。例如改为凌晨1:00或凌晨4:00执行,避开大多数地区夏令时切换的敏感时段。
不同时区成员看到的"9:00"是不同的。一个分布在上海、旧金山和伦敦的团队,如果各自在本地"9:00"执行Cron任务,实际触发的时间点分别是UTC+8、UTC-7和UTC+1,三者之间最多相差15个小时。这会导致协作混乱——上海成员触发的任务结果,旧金山成员可能在8小时后才能看到。
建议在国际团队中使用UTC统一调度。如果团队成员分布在多个时区,最佳做法是约定一个标准时区(通常为UTC)作为所有Cron任务的参考时区。每个成员在编写Cron表达式时,先将目标执行时间换算为UTC时间,再写入表达式。这样所有人的任务都基于同一时间基准运行。
在CronCreate时注明使用哪个时区。Claude Code在创建Cron任务时,建议在任务描述或备注中明确标注"此任务基于UTC+8调度"或"参考时区:Asia/Shanghai"。这不仅能帮助自己日后回顾,也能让其他协作者快速理解任务的调度基准。
任务执行时间的文档化记录。建议在项目文档或README中统一记录Cron任务的调度时区,并说明DST的处理方式。如果后续有时区调整(如团队某成员迁往不同时区),同步更新相关文档,避免因信息不一致导致任务调度混乱。
确认系统当前时区的方法。在Linux/macOS中可以使用命令 timedatectl 或 date +%Z 查看当前时区,Windows中使用 tzutil /g。这些命令能帮助你确认Claude Code读取到的系统时区是否与预期一致。
验证Cron表达式在当前时区下的行为。可以在本地编写一个测试脚本来模拟Cron调度逻辑——手工将当前时间拨到目标时刻附近,观察任务是否按预期触发。对于复杂的调度场景,建议使用在线Cron表达式验证工具(如crontab.guru)辅助排查。
CronList显示的任务创建时间和时区。Claude Code的CronList输出中包含了任务的创建时间和当前所使用的时区信息。如果发现任务创建时间与你本地时间有明显偏移,首先检查系统时区设置是否正确。
时区设置错误导致任务异常的排查:如果Cron任务没有按预期时间触发,排查路径是:第一步检查系统时区(timedatectl),第二步确认Claude Code读取到的时区与系统一致,第三步在已知时区下重新验证Cron表达式的触发时间。通常大部分问题都源于系统时区被意外更改或Cron表达式中的时间与实际意图偏移。
关键任务避免安排在时区切换边界。如前所述,DST切换会造成跳执行或重复执行。对于不能接受跳过或重复的任务,尽量安排在远离切换窗口的时间段。如果确实无法避免,在任务逻辑中增加时间戳校验和幂等性处理。
国际项目统一使用UTC+8或UTC。对于以中国团队为主的项目推荐使用UTC+8(北京时间),对于真正全球分布的项目推荐使用UTC。选定后所有Cron表达式、日志时间戳、任务描述统一使用该时区,避免混淆。
文档中明确标注Cron表达式的参考时区。在Cron任务列表、项目README或任务配置文件中,为每个定时任务附加一行时区说明。例如:"# 每天早上9:00执行数据备份(UTC+8)"或"timezone: Asia/Shanghai"。这样无论团队如何变动,调度意图始终清晰。
定期验证Cron任务在正确时间执行。建议每月或每季度检查一次Cron任务的执行日志,确认触发时间与预期一致。特别是在DST切换后的第一天,重点检查切换窗口附近的任务是否表现正常。如发现问题,及时调整表达式或时区配置。