学完这篇，你能写出一个能在命令行稳定跑、不会重复执行、出错能查的 PHP 脚本，并把它正确地挂到 crontab 上。
第一步：先确认 CLI 环境和 FPM 是两套东西
先看你的机器上 PHP 命令行版本：
which php # 命令路径
php -v # 版本
php -m # 已加载扩展
php --ini # CLI 实际读取的 php.ini 位置
在脚本里判断当前是不是 CLI 模式：
if (PHP_SAPI !== 'cli') {
exit('本脚本只能命令行运行');
}
注意：CLI 的 php.ini 和 PHP-FPM 的往往不是同一个文件。你在宝塔面板里改了内存限制、时区，FPM 生效了，命令行可能还是旧值——php --ini 看到的那份才是准的。宝塔的 PHP 可执行文件一般在 /www/server/php/74/bin/php。
第二步：写一个规范的入口文件
一个能用的最小骨架：
#!/usr/bin/env php
<?php
declare(strict_types=1);
if (PHP_SAPI !== 'cli') { exit('only cli'); }
$opts = getopt('', ['task:', 'days::', 'dry-run']);
$task = $opts['task'] ?? '';
$days = (int)($opts['days'] ?? 30);
$dry = isset($opts['dry-run']);
if ($task === '') {
fwrite(STDERR, "用法: php run.php --task=clean --days=30\n");
exit(1);
}
运行方式：
php run.php --task=clean --days=30 --dry-run
几个约定俗成的规矩：
- 正常信息写
STDOUT，错误写 STDERR，别全用 echo 混在一起；
- 成功
exit(0)，失败 exit(1)，这样 crontab 的邮件告警才有意义；
- 加
--dry-run 参数先空跑一遍，尤其是删除类任务；
- 需要多行输出时用
PHP_EOL，不要写死 \n。
注意：CLI 下没有 $_SERVER['HTTP_HOST']、没有 $_SESSION。凡是代码里靠 HTTP_HOST 拼绝对地址的地方，在命令行都会报 undefined index，记得先兜底或跳过。
第三步：把配置和数据库抽成公共 bootstrap
别把连接代码抄两遍。建一个 bootstrap.php，Web 和 CLI 都 require 它：
// cli/clean.php
require __DIR__ . '/../bootstrap.php';
bootstrap 里只做三件事：读配置、连数据库、注册自动加载。输出缓冲、Session、CSRF 相关的代码一律不要放进去——CLI 用不上，还会报错。
第四步：加文件锁，防止任务重叠
定时任务最经典的坑：5 分钟一次，上一次跑了 8 分钟，结果两个进程同时跑同一批数据。用 flock 解决：
$lock = fopen(sys_get_temp_dir() . '/clean.lock', 'c');
if (!flock($lock, LOCK_EX | LOCK_NB)) {
fwrite(STDERR, "上一次任务仍在运行，本次跳过\n");
exit(0);
}
// ... 你的业务逻辑 ...
flock($lock, LOCK_UN);
fclose($lock);
注意：被锁挡住时退出码用 0 而不是 1。否则每次跳过都会触发 cron 发告警邮件，很快就没人看告警了。
第五步：写进 crontab
crontab -e
格式是「分 时 日 月 周 + 命令」，下面是每 5 分钟跑一次、日志追加到文件的例子：
*/5 * * * * /www/server/php/74/bin/php /www/wwwroot/mysite/cli/clean.php --task=clean --days=30 >> /www/wwwroot/mysite/logs/cron.log 2>&1
三个要点：
- php 必须写绝对路径。crontab 的
PATH 极简，通常只有 /usr/bin:/bin，直接写 php 会出现「手动能跑、定时不跑」。
>> ... 2>&1 别省。这是唯一能看到报错的地方，否则出错信息只发本地邮件，服务器不发邮件就等于石沉大海。- 日志文件要可写。用
www 用户跑的命令，日志目录也得归 www，权限不对直接静默失败。
注意：不要用 curl 去请求站内的一个 URL 来当定时任务。HTTP 请求有超时、会走完整框架启动流程、还可能撞上 CSRF 校验，既慢又不可靠。
第六步：日志里带上时间和结果
function log_line(string $msg): void {
fwrite(STDOUT, '[' . date('Y-m-d H:i:s') . '] ' . $msg . PHP_EOL);
}
每次任务结束打印处理条数，比如 log_line("清理完成，共删除 {$n} 条")。等哪天数据不对，翻日志能直接定位到是哪一次执行出的问题。
第七步：懒触发——不想配 crontab 的替代方案
如果主机不给 crontab 权限，还有一招：把定时任务的判断塞进正常请求里，用户访问时顺便检查「距上次执行是否超过间隔」。
function lazy_cron(string $key, int $interval, callable $job): void {
$file = sys_get_temp_dir() . '/cron_' . md5($key);
$last = is_file($file) ? (int)file_get_contents($file) : 0;
if (time() - $last < $interval) return;
file_put_contents($file, (string)time(), LOCK_EX);
$job();
}
优点是零配置，缺点是没人访问就不执行——低峰期该跑的任务会一直拖。所以它只适合「晚跑一会儿也没关系」的任务，比如统计刷新、缓存预热。
Clara BBS 这类系统走的就是这个思路：插件的定时任务用 Cron::register 注册，懒触发、零配置，后台「系统工具 → 计划任务」里统一管理，不需要你去服务器改 crontab。代价同样明显——站点没流量时任务会延后。
注意：懒触发有并发竞态，高流量站点可能同时触发多个进程。稳妥做法是先写时间戳再执行，并配合本地锁。
小结
- CLI 和 FPM 共用代码、不共用配置，
php --ini 看的是 CLI 那份；
- 入口脚本判断
PHP_SAPI、用 getopt 收参数、用退出码表达成败；
- 配置和数据库放 bootstrap，CLI 与 Web 共用，别抄两遍；
- 用
flock 防重叠，被跳过的执行返回退出码 0；
- crontab 里命令和日志都用绝对路径，别忘
2>&1；
- 别用
curl 调站内 URL 当定时任务；
- 没有 crontab 权限时用懒触发兜底，但要接受「没流量就不跑」。
正式会员
认证极客
钻石卡会员
