@EnableScheduling必须加在@Configuration类上（如主启动类），否则@Scheduled无效；cron表达式需合法且建议显式指定时区；方法须public void无参；多实例需分布式锁。
@EnableScheduling 必须加在配置类上，否则 @Scheduled 无效
Spring Boot 不会自动开启定时任务支持，@EnableScheduling 是开关，不是“可有可无的装饰”。它必须出现在某个被 Spring 扫描到的 @Configuration 类里（比如主启动类或单独的配置类），且只能出现一次。常见错误是把它写在 @Service 或 @Component 类里——这些类不参与配置加载流程，注解会被忽略。
实操建议：
- 最稳妥的位置是主启动类（即标注
@SpringBootApplication的类）上直接加@EnableScheduling - 如果拆分配置，确保该类有
@Configuration，且未被@ConditionalOnMissingBean等条件排除 - 启动时留意日志：若看到
Skipping scheduled task registration或没打印任何ScheduledTaskRegistrar相关日志，大概率是@EnableScheduling没生效
@Scheduled 的 cron 表达式容易因时区或非法格式崩溃
@Scheduled(cron = "...") 启动时就会校验表达式合法性，一旦写错（比如少一位、用中文空格、年份字段误填），应用直接启动失败，报错信息类似：Caused by: java.lang.IllegalArgumentException: Invalid cron expression。更隐蔽的问题是时区：cron 默认按 JVM 本地时区解析，但服务器和开发机时区不一致时，任务执行时间会偏移。
实操建议：
- 用在线工具（如 crontab.guru）验证表达式逻辑，再粘贴进代码；避免手写“* * * * * ?”这类看似通用实则非法的写法（Spring 的 cron 是 6 或 7 位，末尾
?只能用于日/周互斥场景） - 显式指定时区：
@Scheduled(cron = "0 0 2 * * ?", zone = "Asia/Shanghai")，比依赖 JVM 时区更可靠 - 简单周期优先用
fixedDelay或fixedRate，比如@Scheduled(fixedDelay = 60000)，避开 cron 解析风险
@Scheduled 方法必须是 public、无参数、返回 void
Spring 的定时任务代理机制依赖反射调用，对方法签名有硬性约束。如果方法是 private、protected、带参数、返回非 void，运行时不会报错，但任务永远不会执行——连日志都不会输出，非常难排查。
实操建议：
- 方法必须声明为
public void methodName()，哪怕它只在本类内使用 - 不要试图传参（比如想把配置项塞进去），需通过
@Value、@Autowired在方法内部取值 - 如果需要动态控制执行逻辑，用
@ConditionalOnProperty控制整个 Bean 是否注册，而不是在方法里 if-else 跳过业务
多实例部署时，@Scheduled 会重复触发，必须加分布式锁
Spring 原生 @Scheduled 是单机行为。当服务部署多个节点（比如 K8s 多副本、Tomcat 集群），每个实例都会独立执行同一任务，导致数据重复处理、接口频次超限等问题。这不是配置问题，而是架构限制。
实操建议：
- 确认业务是否允许重复：日志归档、缓存预热等幂等操作可暂不处理；订单同步、支付回调等强一致性场景必须干预
- 轻量方案：用 Redis 实现简单锁，任务开始前
SETNX获取锁，设置过期时间，结束后DEL；注意避免锁误删（需 Lua 脚本保证原子性） - 生产环境推荐集成
ShedLock：引入shedlock-spring依赖，加@SchedulerLock注解，底层自动用 Redis / JDBC 等做分布式协调
真正麻烦的从来不是怎么写第一个定时任务，而是当它跑在第十台机器上时，你忘了它还在每台机器上各跑一遍。
