如何配置Yii框架后台定时任务及自动化执行详解？

本文共计901个文字，预计阅读时间需要4分钟。

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杀进程

真正麻烦的从来不是“怎么写个定时任务”，而是“怎么让几十个任务长期稳定、可查、可停、不打架”。路径选错，后期补救成本远高于初期多花半小时搭好调度骨架。