任务调度

介绍
定义调度
运行调度器
- 亚分钟调度任务
- 本地运行调度器
任务输出
任务钩子
事件

介绍

过去，您可能为每个需要在服务器上调度的任务编写了一个 cron 配置条目。然而，这很快就会变得麻烦，因为您的任务调度不再在源代码控制中，您必须 SSH 到服务器以查看现有的 cron 条目或添加其他条目。

Laravel 的命令调度器提供了一种全新的方法来管理服务器上的计划任务。调度器允许您在 Laravel 应用程序中流畅且富有表现力地定义命令调度。在使用调度器时，服务器上只需要一个 cron 条目。您的任务调度通常在应用程序的 routes/console.php 文件中定义。

定义调度

您可以在应用程序的 routes/console.php 文件中定义所有计划任务。首先，让我们看一个示例。在此示例中，我们将计划每天午夜调用一个闭包。在闭包中，我们将执行一个数据库查询以清除表：

php

<?php

use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Schedule;

Schedule::call(function () {
    DB::table('recent_users')->delete();
})->daily();

除了使用闭包进行调度外，您还可以调度可调用对象。可调用对象是包含 __invoke 方法的简单 PHP 类：

php

Schedule::call(new DeleteRecentUsers)->daily();

如果您希望将 routes/console.php 文件保留为仅用于命令定义，您可以在应用程序的 bootstrap/app.php 文件中使用 withSchedule 方法来定义计划任务。此方法接受一个接收调度器实例的闭包：

php

use Illuminate\Console\Scheduling\Schedule;

->withSchedule(function (Schedule $schedule) {
    $schedule->call(new DeleteRecentUsers)->daily();
})

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

shell

php artisan schedule:list

调度 Artisan 命令

除了调度闭包，您还可以调度 Artisan 命令和系统命令。例如，您可以使用 command 方法通过命令的名称或类来调度 Artisan 命令。

在使用命令的类名调度 Artisan 命令时，您可以传递一个数组，其中包含在调用命令时应提供的其他命令行参数：

php

use App\Console\Commands\SendEmailsCommand;
use Illuminate\Support\Facades\Schedule;

Schedule::command('emails:send Taylor --force')->daily();

Schedule::command(SendEmailsCommand::class, ['Taylor', '--force'])->daily();

调度 Artisan 闭包命令

如果您想调度由闭包定义的 Artisan 命令，可以在命令定义后链接调度相关方法：

php

Artisan::command('delete:recent-users', function () {
    DB::table('recent_users')->delete();
})->purpose('Delete recent users')->daily();

如果需要将参数传递给闭包命令，可以将它们提供给 schedule 方法：

php

Artisan::command('emails:send {user} {--force}', function ($user) {
    // ...
})->purpose('Send emails to the specified user')->schedule(['Taylor', '--force'])->daily();

调度队列任务

job 方法可用于调度队列任务。此方法提供了一种方便的方法来调度队列任务，而无需使用 call 方法定义队列任务的闭包：

php

use App\Jobs\Heartbeat;
use Illuminate\Support\Facades\Schedule;

Schedule::job(new Heartbeat)->everyFiveMinutes();

可以为 job 方法提供可选的第二个和第三个参数，这些参数指定用于排队任务的队列名称和队列连接：

php

use App\Jobs\Heartbeat;
use Illuminate\Support\Facades\Schedule;

// 将任务分派到 "heartbeats" 队列上的 "sqs" 连接...
Schedule::job(new Heartbeat, 'heartbeats', 'sqs')->everyFiveMinutes();

调度 Shell 命令

exec 方法可用于向操作系统发出命令：

php

use Illuminate\Support\Facades\Schedule;

Schedule::exec('node /home/forge/script.js')->daily();

调度频率选项

我们已经看到了一些如何配置任务以在指定间隔运行的示例。但是，您可以为任务分配更多的任务调度频率：

方法	描述
`->cron('* * * * *');`	在自定义的 cron 调度上运行任务。
`->everySecond();`	每秒运行一次任务。
`->everyTwoSeconds();`	每两秒运行一次任务。
`->everyFiveSeconds();`	每五秒运行一次任务。
`->everyTenSeconds();`	每十秒运行一次任务。
`->everyFifteenSeconds();`	每十五秒运行一次任务。
`->everyTwentySeconds();`	每二十秒运行一次任务。
`->everyThirtySeconds();`	每三十秒运行一次任务。
`->everyMinute();`	每分钟运行一次任务。
`->everyTwoMinutes();`	每两分钟运行一次任务。
`->everyThreeMinutes();`	每三分钟运行一次任务。
`->everyFourMinutes();`	每四分钟运行一次任务。
`->everyFiveMinutes();`	每五分钟运行一次任务。
`->everyTenMinutes();`	每十分钟运行一次任务。
`->everyFifteenMinutes();`	每十五分钟运行一次任务。
`->everyThirtyMinutes();`	每三十分钟运行一次任务。
`->hourly();`	每小时运行一次任务。
`->hourlyAt(17);`	每小时在 17 分钟时运行任务。
`->everyOddHour($minutes = 0);`	每隔一小时运行一次任务。
`->everyTwoHours($minutes = 0);`	每两小时运行一次任务。
`->everyThreeHours($minutes = 0);`	每三小时运行一次任务。
`->everyFourHours($minutes = 0);`	每四小时运行一次任务。
`->everySixHours($minutes = 0);`	每六小时运行一次任务。
`->daily();`	每天午夜运行任务。
`->dailyAt('13:00');`	每天 13:00 运行任务。
`->twiceDaily(1, 13);`	每天 1:00 和 13:00 运行任务。
`->twiceDailyAt(1, 13, 15);`	每天 1:15 和 13:15 运行任务。
`->weekly();`	每周日 00:00 运行任务。
`->weeklyOn(1, '8:00');`	每周一 8:00 运行任务。
`->monthly();`	每月的第一天 00:00 运行任务。
`->monthlyOn(4, '15:00');`	每月 4 日 15:00 运行任务。
`->twiceMonthly(1, 16, '13:00');`	每月的 1 日和 16 日 13:00 运行任务。
`->lastDayOfMonth('15:00');`	每月的最后一天 15:00 运行任务。
`->quarterly();`	每季度的第一天 00:00 运行任务。
`->quarterlyOn(4, '14:00');`	每季度的第 4 天 14:00 运行任务。
`->yearly();`	每年的第一天 00:00 运行任务。
`->yearlyOn(6, 1, '17:00');`	每年 6 月 1 日 17:00 运行任务。
`->timezone('America/New_York');`	设置任务的时区。

这些方法可以与其他约束条件结合使用，以创建仅在一周的某些天运行的更精细的调度。例如，您可以安排一个命令在每周一运行：

php

use Illuminate\Support\Facades\Schedule;

// 每周一下午 1 点运行一次...
Schedule::call(function () {
    // ...
})->weekly()->mondays()->at('13:00');

// 在工作日的上午 8 点到下午 5 点之间每小时运行一次...
Schedule::command('foo')
    ->weekdays()
    ->hourly()
    ->timezone('America/Chicago')
    ->between('8:00', '17:00');

以下是其他调度约束的列表：

方法	描述
`->weekdays();`	将任务限制为工作日。
`->weekends();`	限制任务在周末运行。
`->sundays();`	限制任务在周日运行。
`->mondays();`	限制任务在周一运行。
`->tuesdays();`	限制任务在周二运行。
`->wednesdays();`	限制任务在周三运行。
`->thursdays();`	限制任务在周四运行。
`->fridays();`	限制任务在周五运行。
`->saturdays();`	限制任务在周六运行。
`->days(array\|mixed);`	限制任务在特定的日子运行。
`->between($startTime, $endTime);`	限制任务在开始和结束时间之间运行。
`->unlessBetween($startTime, $endTime);`	限制任务不在开始和结束时间之间运行。
`->when(Closure);`	基于真值测试限制任务。
`->environments($env);`	限制任务仅在特定环境中运行。

日期约束

days 方法可用于将任务的执行限制在一周中的特定日期。例如，您可以安排一个命令在每周的周日和周三每小时运行一次：

php

use Illuminate\Support\Facades\Schedule;

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

或者，您可以在定义任务应运行的日期时使用 Illuminate\Console\Scheduling\Schedule 类中可用的常量：

php

use Illuminate\Support\Facades;
use Illuminate\Console\Scheduling\Schedule;

Facades\Schedule::command('emails:send')
    ->hourly()
    ->days([Schedule::SUNDAY, Schedule::WEDNESDAY]);

时间约束之间

between 方法可用于根据一天中的时间限制任务的执行：

php

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

同样，unlessBetween 方法可用于在一段时间内排除任务的执行：

php

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

真值测试约束

when 方法可用于根据给定真值测试的结果限制任务的执行。换句话说，如果给定的闭包返回 true，则只要没有其他限制条件阻止任务运行，任务就会执行：

php

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

skip 方法可以看作是 when 的反义词。如果 skip 方法返回 true，则不会执行计划的任务：

php

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

当使用链式的 when 方法时，只有在所有 when 条件返回 true 时，计划的命令才会执行。

环境约束

environments 方法可用于仅在给定环境（由应用程序的 APP_ENV 环境变量定义）上执行任务：

php

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

时区

使用 timezone 方法，您可以指定计划任务的时间应在给定时区内解释：

php

use Illuminate\Support\Facades\Schedule;

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

如果您反复为所有计划任务分配相同的时区，可以通过在应用程序的 app 配置文件中定义 schedule_timezone 选项来指定应为所有计划分配哪个时区：

php

'timezone' => 'UTC',

'schedule_timezone' => 'America/Chicago',

WARNING

请记住，某些时区使用夏令时。当夏令时变化发生时，计划任务可能会运行两次甚至根本不运行。因此，我们建议尽可能避免使用时区调度。

防止任务重叠

默认情况下，即使任务的上一个实例仍在运行，计划任务也会运行。为防止这种情况，您可以使用 withoutOverlapping 方法：

php

use Illuminate\Support\Facades\Schedule;

Schedule::command('emails:send')->withoutOverlapping();

在此示例中，如果 emails:send Artisan 命令尚未运行，它将每分钟运行一次。withoutOverlapping 方法在您有执行时间变化很大的任务时特别有用，可以防止您无法准确预测给定任务需要多长时间。

如果需要，您可以指定在“无重叠”锁过期之前必须经过多少分钟。默认情况下，锁将在 24 小时后过期：

php

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

在后台，withoutOverlapping 方法利用应用程序的缓存来获取锁。如果需要，您可以使用 schedule:clear-cache Artisan 命令清除这些缓存锁。这通常仅在由于意外的服务器问题导致任务卡住时才需要。

在一台服务器上运行任务

WARNING

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

如果应用程序的调度程序在多台服务器上运行，您可以限制计划任务仅在一台服务器上执行。例如，假设您有一个计划任务，每周五晚上生成一份新报告。如果任务调度程序在三台工作服务器上运行，则计划任务将在所有三台服务器上运行并生成三次报告。这可不太好！

要指示任务仅在一台服务器上运行，请在定义计划任务时使用 onOneServer 方法。第一个获取任务的服务器将对作业获得原子锁，以防止其他服务器同时运行相同的任务：

php

use Illuminate\Support\Facades\Schedule;

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

您可以使用 useCache 方法来自定义调度器用于获取单服务器任务所需的原子锁的缓存存储：

php

Schedule::command('recipes:sync')
    ->everyThirtyMinutes()
    ->onOneServer();
    ->useCache('database');

命名单服务器作业

有时，您可能需要安排相同的作业以使用不同的参数进行调度，同时仍指示 Laravel 在一台服务器上运行作业的每个变体。为此，您可以通过 name 方法为每个计划定义分配一个唯一名称：

php

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 方法中定义的顺序依次执行。如果您有长时间运行的任务，这可能会导致后续任务的启动时间比预期的要晚。如果您希望在后台运行任务，以便它们可以同时运行，可以使用 runInBackground 方法：

php

use Illuminate\Support\Facades\Schedule;

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

WARNING

runInBackground 方法仅可用于通过 command 和 exec 方法调度任务时使用。

维护模式

当应用程序处于维护模式时，计划任务将不会运行，因为我们不希望您的任务干扰您可能在服务器上执行的任何未完成的维护。但是，如果您希望即使在维护模式下也强制执行任务，可以在定义任务时调用 evenInMaintenanceMode 方法：

php

Schedule::command('emails:send')->evenInMaintenanceMode();

计划组

在定义具有相似配置的多个计划任务时，您可以使用 Laravel 的任务分组功能来避免为每个任务重复相同的设置。分组任务可以简化代码并确保相关任务的一致性。

要创建一组计划任务，请调用所需的任务配置方法，然后调用 group 方法。group 方法接受一个负责定义共享指定配置的任务的闭包：

php

use Illuminate\Support\Facades\Schedule;

Schedule::daily()
    ->onOneServer()
    ->timezone('America/New_York')
    ->group(function () {
        Schedule::command('emails:send --force');
        Schedule::command('emails:prune');
    });

运行调度器

现在我们已经了解了如何定义计划任务，让我们讨论如何在服务器上实际运行它们。schedule:run Artisan 命令将评估所有计划任务，并根据服务器的当前时间确定它们是否需要运行。

因此，在使用 Laravel 的调度器时，我们只需要在服务器上添加一个 cron 配置条目，该条目每分钟运行一次 schedule:run 命令。如果您不知道如何将 cron 条目添加到服务器，请考虑使用托管平台，例如 Laravel Cloud，它可以为您管理计划任务的执行：

shell

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

亚分钟调度任务

在大多数操作系统上，cron 作业最多只能每分钟运行一次。然而，Laravel 的调度器允许您安排任务以更频繁的间隔运行，甚至可以每秒运行一次：

php

use Illuminate\Support\Facades\Schedule;

Schedule::call(function () {
    DB::table('recent_users')->delete();
})->everySecond();

当应用程序中定义了亚分钟任务时，schedule:run 命令将在当前分钟结束之前继续运行，而不是立即退出。这允许命令在整个分钟内调用所有需要的亚分钟任务。

由于运行时间超过预期的亚分钟任务可能会延迟后续亚分钟任务的执行，因此建议所有亚分钟任务调度队列作业或后台命令来处理实际的任务处理：

php

use App\Jobs\DeleteRecentUsers;

Schedule::job(new DeleteRecentUsers)->everyTenSeconds();

Schedule::command('users:delete')->everyTenSeconds()->runInBackground();

中断亚分钟任务

由于在定义了亚分钟任务时，schedule:run 命令将在调用的整个分钟内运行，因此在部署应用程序时，您可能有时需要中断命令。否则，已经运行的 schedule:run 命令实例将继续使用应用程序先前部署的代码，直到当前分钟结束。

要中断正在进行的 schedule:run 调用，您可以将 schedule:interrupt 命令添加到应用程序的部署脚本中。此命令应在应用程序完成部署后调用：

shell

php artisan schedule:interrupt

本地运行调度器

通常，您不会在本地开发机器上添加调度器 cron 条目。相反，您可以使用 schedule:work Artisan 命令。此命令将在前台运行，并每分钟调用调度器，直到您终止命令。当定义了亚分钟任务时，调度器将在每分钟内继续运行以处理这些任务：

shell

php artisan schedule:work

任务输出

Laravel 调度器提供了几种方便的方法来处理计划任务生成的输出。首先，使用 sendOutputTo 方法，您可以将输出发送到文件以供以后检查：

php

use Illuminate\Support\Facades\Schedule;

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

如果您希望将输出附加到给定文件，可以使用 appendOutputTo 方法：

php

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

使用 emailOutputTo 方法，您可以将输出通过电子邮件发送到您选择的电子邮件地址。在通过电子邮件发送任务的输出之前，您应该配置 Laravel 的电子邮件服务：

php

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

如果您只希望在计划的 Artisan 或系统命令以非零退出代码终止时通过电子邮件发送输出，请使用 emailOutputOnFailure 方法：

php

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

WARNING

emailOutputTo、emailOutputOnFailure、sendOutputTo 和 appendOutputTo 方法仅适用于 command 和 exec 方法。

任务钩子

使用 before 和 after 方法，您可以指定在计划任务执行之前和之后执行的代码：

php

use Illuminate\Support\Facades\Schedule;

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

onSuccess 和 onFailure 方法允许您指定在计划任务成功或失败时执行的代码。失败表示计划的 Artisan 或系统命令以非零退出代码终止：

php

Schedule::command('emails:send')
    ->daily()
    ->onSuccess(function () {
        // 任务成功...
    })
    ->onFailure(function () {
        // 任务失败...
    });

如果您的命令有可用的输出，您可以通过在钩子闭包定义中类型提示 Illuminate\Support\Stringable 实例来访问 after、onSuccess 或 onFailure 钩子中的输出：

php

use Illuminate\Support\Facades\Schedule;
use Illuminate\Support\Stringable;

Schedule::command('emails:send')
    ->daily()
    ->onSuccess(function (Stringable $output) {
        // 任务成功...
    })
    ->onFailure(function (Stringable $output) {
        // 任务失败...
    });

Pinging URLs

使用 pingBefore 和 thenPing 方法，调度器可以在任务执行之前或之后自动 ping 给定的 URL。此方法对于通知外部服务（如 Envoyer）您的计划任务开始或已完成执行非常有用：

php

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

pingOnSuccess 和 pingOnFailure 方法可用于仅在任务成功或失败时 ping 给定的 URL。失败表示计划的 Artisan 或系统命令以非零退出代码终止：

php

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

pingBeforeIf、thenPingIf、pingOnSuccessIf 和 pingOnFailureIf 方法可用于仅在给定条件为 true 时 ping 给定的 URL：

php

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

Schedule::command('emails:send')
    ->daily()
    ->pingOnSuccessIf($condition, $successUrl)
    ->pingOnFailureIf($condition, $failureUrl);

事件

Laravel 在调度过程中会调度各种事件。您可以为以下任何事件定义监听器：

事件名称
`Illuminate\Console\Events\ScheduledTaskStarting`
`Illuminate\Console\Events\ScheduledTaskFinished`
`Illuminate\Console\Events\ScheduledBackgroundTaskFinished`
`Illuminate\Console\Events\ScheduledTaskSkipped`
`Illuminate\Console\Events\ScheduledTaskFailed`

任务调度 ​

介绍 ​

定义调度 ​

调度 Artisan 命令 ​

调度 Artisan 闭包命令 ​

调度队列任务 ​

调度 Shell 命令 ​

调度频率选项 ​

日期约束 ​

时间约束之间 ​

真值测试约束 ​

环境约束 ​

时区 ​

防止任务重叠 ​

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

命名单服务器作业 ​

后台任务 ​

维护模式 ​

计划组 ​

运行调度器 ​

亚分钟调度任务 ​

中断亚分钟任务 ​

本地运行调度器 ​

任务输出 ​

任务钩子 ​

Pinging URLs ​

事件 ​

任务调度

介绍

定义调度

调度 Artisan 命令

调度 Artisan 闭包命令

调度队列任务

调度 Shell 命令

调度频率选项

日期约束

时间约束之间

真值测试约束

环境约束

时区

防止任务重叠

在一台服务器上运行任务

命名单服务器作业

后台任务

维护模式

计划组

运行调度器

亚分钟调度任务

中断亚分钟任务

本地运行调度器

任务输出

任务钩子

Pinging URLs

事件