任务调度 laravel laravelphp 中文文档

简介
定义调度
运行调度程序
本地运行调度程序
任务输出
任务钩子
事件

简介

过去，你可能需要在服务器上为每一个调度任务去创建 Cron 条目。因为这些任务的调度不是通过代码控制的，你要查看或新增任务调度都需要通过 SSH 远程登录到服务器上去操作，所以这种方式很快会让人变得痛苦不堪。

Laravel 的命令行调度器允许你在 Laravel 中清晰明了地定义命令调度。在使用这个任务调度器时，你只需要在你的服务器上创建单个 Cron 入口。你的任务调度在 php app/Console/Kernel.php 的 php schedule 方法中进行定义。为了帮助你更好的入门，这个方法中有个简单的例子。

定义调度

你可以在 php App\Console\Kernel 类的 php schedule 方法中定义所有的调度任务。在开始之前，我们来看一个例子：我们计划每天午夜执行一个闭包，这个闭包会执行一次数据库语句去清空一张表：

<?php
namespace App\Console;
use Illuminate\Console\Scheduling\Schedule;
use Illuminate\Foundation\Console\Kernel as ConsoleKernel;
use Illuminate\Support\Facades\DB;
class Kernel extends ConsoleKernel
{
    /**
     * 定义应用中的命令调度
     */
    protected function schedule(Schedule $schedule): void
    {
        $schedule->call(function () {
            DB::table('recent_users')->delete();
        })->daily();
    }
}

除了调用闭包这种方式来调度外，你还可以调用可调用对象。可调用对象是简单的 PHP 类，包含一个 php __invoke 方法：

$schedule->call(new DeleteRecentUsers)->daily();

如果你想查看任务计划的概述及其下次计划运行时间，你可以使用 php schedule:list Artisan 命令：

php artisan schedule:list

Artisan 命令调度

调度方式不仅有调用闭包，还有调用 Artisan commands 和操作系统命令。例如，你可以给 command 方法传递命令名称或类来调度一个 php Artisan 命令：

当使用命令类名调度 php Artisan 命令时，你可以通过一个数组传递附加的命令行参数，且这些参数需要在命令触发时提供：

use App\Console\Commands\SendEmailsCommand;
$schedule->command('emails:send Taylor --force')->daily();
$schedule->command(SendEmailsCommand::class, ['Taylor', '--force'])->daily();

队列任务调度

php job 方法可以用来调度 queued job。此方法提供了一种快捷方式来调度任务，而无需使用 php call 方法创建闭包来调度任务：

use App\Jobs\Heartbeat;
$schedule->job(new Heartbeat)->everyFiveMinutes();

php job 方法提供了可选的第二，三参数，分别指定任务将被放置的队列名称及连接：

use App\Jobs\Heartbeat;
// 分发任务到「heartbeats」队列及「sqs」连接...
$schedule->job(new Heartbeat, 'heartbeats', 'sqs')->everyFiveMinutes();

这些方法与额外的约束条件相结合后，可用于创建在一周的特定时间运行甚至更精细的计划任务。例如，在每周一执行命令：

// 在每周一 13:00 执行...
$schedule->call(function () {
    // ...
})->weekly()->mondays()->at('13:00');
// 在每个工作日 8:00 到 17:00 之间的每小时周期执行...
$schedule->command('foo')
          ->weekdays()
          ->hourly()
          ->timezone('America/Chicago')
          ->between('8:00', '17:00');

下方列出了额外的约束条件：

方法描述
php ->weekdays(); 限制任务在工作日执行
php ->weekends(); 限制任务在周末执行
php ->sundays(); 限制任务在周日执行
php ->mondays(); 限制任务在周一执行
php ->tuesdays(); 限制任务在周二执行
php ->wednesdays(); 限制任务在周三执行
php ->thursdays(); 限制任务在周四执行
php ->fridays(); 限制任务在周五执行
php ->saturdays(); 限制任务在周六执行
php ->days(array|mixed); 限制任务在每周的指定日期执行
php ->between($startTime, $endTime); 限制任务在 php $startTime 和 php $endTime 区间执行
php ->unlessBetween($startTime, $endTime); 限制任务不在 php $startTime 和 php $endTime 区间执行
php ->when(Closure); 限制任务在闭包返回为真时执行
php ->environments($env); 限制任务在特定环境中执行

周几（Day）限制
php days 方法可以用于限制任务在每周的指定日期执行。举个例子，你可以在让一个命令每周日和每周三每小时执行一次：

$schedule->command('emails:send')
                ->hourly()
                ->days([0, 3]);

不仅如此，你还可以使用 php Illuminate\Console\Scheduling\Schedule 类中的常量来设置任务在指定日期运行：

use Illuminate\Console\Scheduling\Schedule;
$schedule->command('emails:send')
                ->hourly()
                ->days([Schedule::SUNDAY, Schedule::WEDNESDAY]);

时间范围限制
php between 方法可用于限制任务在一天中的某个时间段执行：

$schedule->command('emails:send')
                    ->hourly()
                    ->between('7:00', '22:00');

同样， php unlessBetween 方法也可用于限制任务不在一天中的某个时间段执行：

$schedule->command('emails:send')
                    ->hourly()
                    ->unlessBetween('23:00', '4:00');

闭包检测限制
php when 方法可根据闭包返回结果来执行任务。换言之，若给定的闭包返回 php true，若无其他限制条件阻止，任务就会一直执行：

$schedule->command('emails:send')->daily()->when(function () {
    return true;
});

php skip 可看作是 php when 的逆方法。若 php skip 方法返回 php true，任务将不会执行：

$schedule->command('emails:send')->daily()->skip(function () {
    return true;
});

当链式调用 php when 方法时，仅当所有 php when 都返回 php true 时，任务才会执行。

环境限制
php environments 方法可限制任务在指定环境中执行（由 php APP_ENV 环境变量定义）：

$schedule->command('emails:send')
            ->daily()
            ->environments(['staging', 'production']);

时区

php timezone 方法可指定在某一时区的时间执行计划任务：

$schedule->command('report:generate')
         ->timezone('America/New_York')
         ->at('2:00')

若想给所有计划任务分配相同的时区，那么需要在 php app/Console/Kernel.php 类中定义 php scheduleTimezone 方法。该方法会返回一个默认时区，最终分配给所有计划任务：

use DateTimeZone;
/**
 * 获取计划事件默认使用的时区
 */
protected function scheduleTimezone(): DateTimeZone|string|null
{
    return 'America/Chicago';
}

注意
请记住，有些时区会使用夏令时。当夏令时发生调整时，你的任务可能会执行两次，甚至根本不会执行。因此，我们建议尽可能避免使用时区来安排计划任务。

避免任务重复

默认情况下，即使之前的任务实例还在执行，调度内的任务也会执行。为避免这种情况的发生，你可以使用 php withoutOverlapping 方法：

$schedule->command('emails:send')->withoutOverlapping();

在此例中，若 php emails:send Artisan 命令还未运行，那它将会每分钟执行一次。如果你的任务执行时间非常不确定，导致你无法准确预测任务的执行时间，那 php withoutOverlapping 方法会特别有用。

如有需要，你可以在 php withoutOverlapping 锁过期之前，指定它的过期分钟数。默认情况下，这个锁会在 24 小时后过期：

$schedule->command('emails:send')->withoutOverlapping(10);

上面这种场景中，php withoutOverlapping 方法使用应用程序的缓存获取锁。如有必要，可以使用php schedule:clear cache Artisan命令清除这些缓存锁。这通常只有在任务由于意外的服务器问题而卡住时才需要。

任务只运行在一台服务器上

注意
要使用此功能，你的应用程序必须使用 php database, php memcached, php dynamodb, 或 php redis 缓存驱动程序作为应用程序的默认缓存驱动程序。此外，所有服务器必须和同一个中央缓存服务器通信。

如果你的应用运行在多台服务器上，可能需要限制调度任务只在某台服务器上运行。例如，假设你有一个每个星期五晚上生成新报告的调度任务，如果任务调度器运行在三台服务器上，调度任务会在三台服务器上运行并且生成三次报告，不够优雅！

要指示任务应仅在一台服务器上运行，请在定义计划任务时使用 php onOneServer 方法。第一台获取到该任务的服务器会给任务上一把原子锁以阻止其他服务器同时运行该任务:

$schedule->command('report:generate')
                ->fridays()
                ->at('17:00')
                ->onOneServer();

命名单服务器作业
有时，你可能需要使用不同的参数调度相同的作业，同时使其仍然在单个服务器上运行作业。为此，你可以使用 php name 方法为每个作业定义一个唯一的名字：

$schedule->job(new CheckUptime('https://laravel.com'))
            ->name('check_uptime:laravel.com')
            ->everyFiveMinutes()
            ->onOneServer();
$schedule->job(new CheckUptime('https://vapor.laravel.com'))
            ->name('check_uptime:vapor.laravel.com')
            ->everyFiveMinutes()
            ->onOneServer();

如果你使用闭包来定义单服务器作业，则必须为他们定义一个名字

$schedule->call(fn () => User::resetApiRequestCount())
    ->name('reset-api-request-count')
    ->daily()
    ->onOneServer();

后台任务

默认情况下，同时运行多个任务将根据它们在 php schedule 方法中定义的顺序执行。如果你有一些长时间运行的任务，将会导致后续任务比预期时间更晚启动。如果你想在后台运行任务，以便它们可以同时运行，则可以使用 php runInBackground 方法:

$schedule->command('analytics:report')
         ->daily()
         ->runInBackground();

注意
php runInBackground 方法只有在通过 php command 和 php exec 方法调度任务时才可以使用

维护模式

当应用处于维护模式时，Laravel 的队列任务将不会运行。因为我们不想调度任务干扰到服务器上可能还未完成的维护项目。不过，如果你想强制任务在维护模式下运行，你可以使用 php evenInMaintenanceMode 方法：

$schedule->command('emails:send')->evenInMaintenanceMode();

运行调度程序

现在，我们已经学会了如何定义计划任务，接下来让我们讨论如何真正在服务器上运行它们。php schedule:run Artisan 命令将评估你的所有计划任务，并根据服务器的当前时间决定它们是否运行。

因此，当使用 Laravel 的调度程序时，我们只需要向服务器添加一个 cron 配置项，该项每分钟运行一次 php schedule:run 命令。如果你不知道如何向服务器添加 cron 配置项，请考虑使用 Laravel Forge 之类的服务来为你管理 cron 配置项：

* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1

本地运行调度程序

通常，你不会直接将 cron 配置项添加到本地开发计算机。你反而可以使用 php schedule:work Artisan 命令。该命令将在前台运行，并每分钟调用一次调度程序，直到你终止该命令为止：

php artisan schedule:work

任务输出

Laravel 调度器提供了一些简便方法来处理调度任务生成的输出。首先，你可以使用 php sendOutputTo 方法将输出发送到文件中以便后续检查：

$schedule->command('emails:send')
         ->daily()
         ->sendOutputTo($filePath);

如果希望将输出追加到指定文件，可使用 php appendOutputTo 方法：

$schedule->command('emails:send')
         ->daily()
         ->appendOutputTo($filePath);

使用 php emailOutputTo 方法，你可以将输出发送到指定邮箱。在发送邮件之前，你需要先配置 Laravel 的邮件服务:

$schedule->command('report:generate')
         ->daily()
         ->sendOutputTo($filePath)
         ->emailOutputTo('taylor@example.com');

如果你只想在命令执行失败时将输出发送到邮箱，可使用 php emailOutputOnFailure 方法：

$schedule->command('report:generate')
         ->daily()
         ->emailOutputOnFailure('taylor@example.com');

注意
php emailOutputTo, php emailOutputOnFailure, php sendOutputTo 和 php appendOutputTo 是 php command 和 php exec 独有的方法。

任务钩子

使用 php before 和 php after 方法，你可以决定在调度任务执行前或者执行后来运行代码：

$schedule->command('emails:send')
         ->daily()
         ->before(function () {
             // 任务即将执行。。。
         })
         ->after(function () {
             // 任务已经执行。。。
         });

使用 php onSuccess 和 php onFailure 方法，你可以决定在调度任务成功或者失败运行代码。失败表示 Artisan 或系统命令以非零退出码终止：

$schedule->command('emails:send')
         ->daily()
         ->onSuccess(function () {
             // 任务执行成功。。。
         })
         ->onFailure(function () {
             // 任务执行失败。。。
         });

如果你的命令有输出，你可以使用php after, php onSuccess 或 php onFailure钩子并传入类型为php Illuminate\Support\Stringable的php $output参数的闭包来访问任务输出：

use Illuminate\Support\Stringable;
$schedule->command('emails:send')
         ->daily()
         ->onSuccess(function (Stringable $output) {
             // The task succeeded...
         })
         ->onFailure(function (Stringable $output) {
             // The task failed...
         });

Pinging 网址
使用 php pingBefore 和 php thenPing 方法，你可以在任务完成之前或完成之后来 ping 指定的 URL。当前方法在通知外部服务，如 Envoyer，计划任务在将要执行或已完成时会很有用：

$schedule->command('emails:send')
         ->daily()
         ->pingBefore($url)
         ->thenPing($url);

只有当条件为 php true 时，才可以使用 php pingBeforeIf 和 php thenPingIf 方法来 ping 指定 URL ：

$schedule->command('emails:send')
         ->daily()
         ->pingBeforeIf($condition, $url)
         ->thenPingIf($condition, $url);

当任务成功或失败时，可使用 php pingOnSuccess 和 php pingOnFailure 方法来 ping 给定 URL。失败表示 Artisan 或系统命令以非零退出码终止：

$schedule->command('emails:send')
         ->daily()
         ->pingOnSuccess($successUrl)
         ->pingOnFailure($failureUrl);

所有 ping 方法都依赖 Guzzle HTTP 库。通常，Guzzle 已在所有新的 Laravel 项目中默认安装，不过，若意外将 Guzzle 删除，则可以使用 Composer 包管理器将 Guzzle 手动安装到项目中：

composer require guzzlehttp/guzzle

事件

如果需要，你可以监听调度程序调度的事件。通常，事件侦听器映射将在你的应用程序的 php App\Providers\EventServiceProvider 类中定义：

/**
 * 应用的事件监听器映射
 *
 * @var array
 */
protected $listen = [
    'Illuminate\Console\Events\ScheduledTaskStarting' => [
        'App\Listeners\LogScheduledTaskStarting',
    ],
    'Illuminate\Console\Events\ScheduledTaskFinished' => [
        'App\Listeners\LogScheduledTaskFinished',
    ],
    'Illuminate\Console\Events\ScheduledBackgroundTaskFinished' => [
        'App\Listeners\LogScheduledBackgroundTaskFinished',
    ],
    'Illuminate\Console\Events\ScheduledTaskSkipped' => [
        'App\Listeners\LogScheduledTaskSkipped',
    ],
    'Illuminate\Console\Events\ScheduledTaskFailed' => [
        'App\Listeners\LogScheduledTaskFailed',
    ],
];