ThinkPHP 8 定时任务需将业务封装为继承think\console\Command的命令类（置于app/command/、命名空间app\command、setName指定命令名），显式注册至app/command.php数组，启用config/console.php中'scheduling'=>true，并通过Linux crontab每分钟执行cd项目根目录&&/usr/bin/php think schedule:run触发。
ThinkPHP 8 的定时任务不是“开个开关就自动跑”，而是把业务逻辑封装成命令 + 由操作系统按时触发。它不内置守护进程，也不轮询等待，必须靠 Linux cron 每分钟调用一次 php think schedule:run 扫描并执行就绪任务。配置对了才真能按时干活，错一个环节——比如路径、环境、注册、权限——任务就静默失效。
命令类必须规范创建
所有可调度的逻辑，必须写在继承 think\console\Command 的类里，且严格满足以下四点：
- 文件放在
app/command/目录下（注意是小写command，不是Console/Commands） - 命名空间固定为
app\command，类名与文件名完全一致（如app/command/SyncOrder.php对应class SyncOrder） -
configure()方法中必须调用$this->setName('sync:order')（名称不含空格、特殊字符，推荐用冒号分组） -
execute()里写真实业务，避免exit()、未捕获 fatal error 或阻塞操作
命令必须显式注册
ThinkPHP 不会自动扫描 app/command/，必须手动注册到框架。确保项目中存在 app/command.php 文件，内容为返回数组：
<?php
return [
'app\command\CleanCache',
'app\command\SyncOrder',
'app\command\SendNotice',
];哪怕只注册一个命令，也必须是数组格式；漏写命名空间、大小写错误、多写空格，都会导致 php think list 看不到该命令。
立即学习“PHP免费学习笔记（深入）”；
调度器需启用且环境匹配
php think schedule:run 默认只在 APP_ENV === 'production' 下执行调度逻辑。开发调试时可用：
APP_ENV=production php think schedule:run -v
同时检查 config/console.php 中是否已开启调度：
'scheduling' => true,
此项为 TP8.0+ 强制要求，缺则整个调度链路不启动。
Crontab 配置要精准可靠
Linux 定时任务不能依赖 shell 环境，必须用绝对路径并明确工作目录：
*/1 * * * * cd /var/www/myapp && /usr/bin/php think schedule:run >> /dev/null 2>&1
关键细节：
-
/usr/bin/php：用which php确认真实路径，避免 cron 因 PATH 缺失找不到 PHP -
cd /var/www/myapp：确保工作目录正确，否则无法加载配置、读取 .env、写入 runtime - 日志重定向建议保留：
>> /var/log/tp-cron.log 2>&1，便于排查失败原因 - 运行用户要有权限：对
runtime/可写、对.env可读、对命令文件可执行
测试与排障建议
上线前务必逐项验证：
- 终端执行
php think list，确认你的命令出现在列表中 - 手动运行命令：
php think clean:cache，看是否正常输出、逻辑生效 - 临时加一条最简 crontab：
* * * * * cd /path && /usr/bin/php think test:ping >> /tmp/cron-test.log 2>&1，等 1 分钟检查日志是否写入 - 查看
runtime/log/和 cron 日志，留意“Command not defined”“Class not found”“Permission denied”等典型报错
本质上，ThinkPHP 8 的定时任务是框架能力与系统调度的协作结果——你负责把活儿写清楚，系统负责准时敲门。不复杂，但每一步都得踩准。
