Yii框架定时任务需通过外部系统（如crontab）调用继承yii\console\Controller的Console命令实现，核心是定义actionXxx方法并配置绝对路径、正确PHP环境及日志错误处理。
Yii框架本身不内置调度器，定时任务必须靠外部系统（如Linux crontab）触发控制台命令来实现。直接在代码里写“每5分钟执行一次”是无效的——那只是个字符串，没人会自动读它。
怎么写一个可被crontab调用的Console命令
核心是继承 yii\console\Controller，方法名必须是 actionXxx 形式，且不能带参数（除非你明确声明并接受）：
- 命令类放在
commands/目录下，比如app\commands\CleanCacheController -
actionRun()是最常用的入口，执行时运行php yii clean-cache/run - 若想支持传参，得显式定义形参：
public function actionSendEmails($limit = 10, $force = false)，调用时写成php yii clean-cache/send-emails 100 --force=1 - 不要在
__construct()或init()里放耗时逻辑——命令未真正触发前就可能失败
crontab配置里最容易出错的三处
很多任务“看起来写了，但根本没跑”，问题常卡在这几个地方：
-
/usr/bin/php路径不对：用which php确认真实路径，别直接抄文档里的默认值 - 项目路径写错：crontab里
/path/to/yii必须是绝对路径，且该路径下存在可执行的yii文件（通常是根目录那个PHP脚本） - 环境变量缺失：crontab默认不加载用户shell环境，
PATH很短，导致找不到php或连不上数据库；稳妥做法是在crontab行首加PATH=/usr/local/bin:/usr/bin:/bin
正确示例：0 * * * * PATH=/usr/bin:/bin /usr/bin/php /var/www/myapp/yii clean-cache/run >> /var/log/cron-clean.log 2>&1
为什么建议用 omnilight/yii2-scheduling 而不是纯crontab
当任务数超过3个，手动维护 crontab -e 就开始反人类了。这个扩展把所有调度规则收归代码管理，只留一个crontab入口：
- 安装后只需在
console.php配置里加一段scheduler组件，再写个ScheduleController::actionSchedule() - 所有任务定义都写在
config/console.php的'tasks'数组里，和业务代码一起提交Git - 避免任务重叠：它默认加锁（基于文件或DB），防止上一次还没跑完，下一次又被触发
- 但注意：它仍依赖一个基础crontab项（如
* * * * * cd /var/www/myapp && php yii schedule/run），不是完全脱离系统调度
日志和错误处理不能省略
后台任务看不见输出，不记录等于没做：
- 用
Yii::info()和Yii::error()记到runtime/logs/app.log，别只靠echo - 捕获异常后必须返回非0退出码：
return 1;，否则crontab无法感知失败，下次还会照常触发 - 避免用
> /dev/null 2>&1掩盖问题——先调试通了再关输出，生产环境至少保留错误重定向到日志文件 - 大任务记得测内存：用
memory_get_peak_usage(true)记录峰值，防止OOM杀进程
真正麻烦的从来不是“怎么写个定时任务”，而是“怎么让几十个任务长期稳定、可查、可停、不打架”。路径选错，后期补救成本远高于初期多花半小时搭好调度骨架。
