任务调度

• 简介
• 定义调度
  • 调度 Artisan 命令
  • 调度队列任务
  • 调度 Shell 命令
  • 调度频率选项
  • 时区
  • 防止任务重叠
  • 在一台服务器上运行任务
  • 后台任务
  • 维护模式
  • 暂停计划任务
  • 调度组
• 运行调度器
  • 子分钟计划任务
  • 本地运行调度器
• 任务输出
• 任务钩子
• 事件

简介

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

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

定义调度

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

<?php

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

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

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

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

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

use Illuminate\Console\Scheduling\Schedule;

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

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

php artisan schedule:list

调度 Artisan 命令

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

使用命令类名调度 Artisan 命令时，可以传递一个额外的命令行参数数组，这些参数应在调用命令时提供给命令：

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 命令，可以在命令定义后链接调度相关方法：

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

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

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

调度队列任务

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

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

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

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

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

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

调度 Shell 命令

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

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');	设置任务的时区。

这些方法可以与额外的约束结合使用，以创建更精细的调度，仅在每周的特定日期运行。例如，您可以调度命令在每周一运行：

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 方法可用于将任务执行限制在每周的特定日期。例如，您可以调度命令在周日和周三每小时运行：

use Illuminate\Support\Facades\Schedule;

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

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

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

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

时间约束

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

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

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

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

真值测试约束

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

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

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

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

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

环境约束

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

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

时区

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

use Illuminate\Support\Facades\Schedule;

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

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

'timezone' => 'UTC',

'schedule_timezone' => 'America/Chicago',

WARNING

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

防止任务重叠

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

use Illuminate\Support\Facades\Schedule;

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

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

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

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

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

在一台服务器上运行任务

WARNING

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

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

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

use Illuminate\Support\Facades\Schedule;

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

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

Schedule::useCache('database');

命名单服务器任务

有时您可能需要调度同一任务以不同参数分发，同时仍指示 Laravel 在单台服务器上运行任务的每个排列。为此，您可以通过 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();

后台任务

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

use Illuminate\Support\Facades\Schedule;

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

WARNING

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

维护模式

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

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

暂停计划任务

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

php artisan schedule:pause

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

php artisan schedule:continue

中断子分钟任务

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

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

php artisan schedule:interrupt

本地运行调度器

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

php artisan schedule:work

任务输出

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

use Illuminate\Support\Facades\Schedule;

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

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

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

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

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

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

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

WARNING

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

任务钩子

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

use Illuminate\Support\Facades\Schedule;

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

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

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

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

use Illuminate\Support\Stringable;

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

Ping URL

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

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

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

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

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

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