任务调度

介绍

过去，你可能需要为服务器上计划的每个任务编写一个 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 运行任务。
`->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;

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

// 工作日从 8 AM 到 5 PM 每小时运行...
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',

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

防止任务重叠

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

在单个服务器上运行任务

要使用此功能，你的应用程序必须使用 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();

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

维护模式

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

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

计划组

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

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

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，它可以为你管理计划任务的执行：

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

亚分钟计划任务

在大多数操作系统上，cron 作业最多每分钟运行一次。但是，Laravel 的调度器允许你计划任务以更频繁的间隔运行，甚至可以像每秒一次：

use Illuminate\Support\Facades\Schedule;

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

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

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

use App\Jobs\DeleteRecentUsers;

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

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

中断亚分钟任务

由于 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');

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`

Strings

认证