任务调度

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

简介

过去，您可能需要在服务器上为需要调度的每个任务编写一个 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('删除最近用户')->daily();

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

php

Artisan::command('emails:send {user} {--force}', function ($user) {
    // ...
})->purpose('向指定用户发送邮件')->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;

// 将作业分派到 "sqs" 连接的 "heartbeats" 队列上...
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 运行任务。
`->daysOfMonth([1, 10, 20]);`	在每月的特定日期运行任务。
`->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;

// 每周一 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');

其他调度约束条件列表如下：

方法	描述
`->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',

警告

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

防止任务重叠

默认情况下，即使任务的先前实例仍在运行，计划任务也会运行。为了防止这种情况，您可以使用 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 命令清除这些缓存锁。通常，仅当任务因意外的服务器问题而卡住时才需要这样做。

在一台服务器上运行任务

警告

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

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

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

php

use Illuminate\Support\Facades\Schedule;

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

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

php

Schedule::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();

类似地，如果计划闭包打算在一台服务器上运行，则必须为其分配一个名称：

php

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

后台任务

默认情况下，多个计划在同一时间执行的任务将根据它们在 schedule 方法中定义的顺序依次执行。如果您有长时间运行的任务，这可能会导致后续任务开始的时间远晚于预期。如果您希望任务在后台运行，以便它们可以同时运行，可以使用 runInBackground 方法：

php

use Illuminate\Support\Facades\Schedule;

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

警告

runInBackground 方法只能在通过 command 和 exec 方法调度任务时使用。

维护模式

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

php

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

暂停计划任务

您可以使用 schedule:pause Artisan 命令临时暂停计划任务处理，而无需更改已部署的代码：

shell

php artisan schedule:pause

当调度器暂停时，不会有计划任务运行。您可以使用 schedule:continue 命令恢复计划任务处理：

shell

php artisan schedule:continue

如果某个任务应该在调度器暂停时仍然运行，您可以使用 evenWhenPaused 方法标记它：

php

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

调度组

当定义多个具有相似配置的计划任务时，您可以使用 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');

警告

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 实例作为 $output 参数，在 after、onSuccess 或 onFailure 钩子中访问它：

php

use Illuminate\Support\Stringable;

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

Ping 网址

使用 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 命令 ​

调度频率选项 ​

日期约束 ​

时间区间约束 ​

真值测试约束 ​

环境约束 ​

时区 ​

防止任务重叠 ​

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

命名单服务器作业 ​

后台任务 ​

维护模式 ​

暂停计划任务 ​

调度组 ​

运行调度器 ​

亚分钟计划任务 ​

中断亚分钟任务 ​

在本地运行调度器 ​

任务输出 ​

任务钩子 ​

Ping 网址 ​

事件 ​

任务调度

简介

定义调度

调度 Artisan 命令

调度 Artisan 闭包命令

调度队列作业

调度 Shell 命令

调度频率选项

日期约束

时间区间约束

真值测试约束

环境约束

时区

防止任务重叠

在一台服务器上运行任务

命名单服务器作业

后台任务

维护模式

暂停计划任务

调度组

运行调度器

亚分钟计划任务

中断亚分钟任务

在本地运行调度器

任务输出

任务钩子

Ping 网址

事件