Laravel Envoy 是一个用于执行您在远程服务器上运行的常见任务的工具。使用 Blade 风格的语法，您可以轻松设置用于部署、Artisan 命令等的任务。目前，Envoy 仅支持 Mac 和 Linux 操作系统。但是，对 Windows 的支持可以通过使用 WSL2 来实现。
首先，使用 Composer 包管理器将 Envoy 安装到你的项目中：
composer require laravel/envoy --devEnvoy 安装完成后，Envoy 二进制文件将位于您的应用程序的 vendor/bin 目录中：
php vendor/bin/envoy任务是 Envoy 的基本构建块。
任务定义了当任务被调用时，应在您的远程服务器上执行的 shell 命令。
例如，您可能定义一个任务，在您的所有应用程序的队列工作服务器上执行 php artisan queue:restart 命令。
你的所有 Envoy 任务都应该定义在应用程序根目录下的 Envoy.blade.php 文件中。这是一个入门示例：
@servers(['web' => ['user@192.168.1.1'], 'workers' => ['user@192.168.1.2']])
@task('restart-queues', ['on' => 'workers'])
cd /home/user/example.com
php artisan queue:restart
@endtask如你所见，文件顶部定义了一个 @servers 数组，允许你通过 on 选项在你的任务声明中引用这些服务器。@servers 声明应始终放在单行上。在你的 @task 声明中，你应该放置当任务被调用时应在你的服务器上执行的 shell 命令。
你可以强制脚本在本地计算机上运行 通过将服务器的 IP 地址指定为 127.0.0.1：
@servers(['localhost' => '127.0.0.1'])使用 @import 指令，你可以导入其他 Envoy 文件，以便它们的 故事 和 任务 被添加到你的文件中。文件导入后，你可以执行它们包含的 任务，就像它们是在你自己的 Envoy 文件中定义的一样：
@import('vendor/package/Envoy.blade.php')Envoy 允许您轻松运行跨多个服务器的任务。首先，将更多服务器添加到您的 @servers 声明中。每个服务器都应分配一个唯一的名称。定义了您的额外服务器后，您可以在任务的 on 数组中列出每个服务器：
@servers(['web-1' => '192.168.1.1', 'web-2' => '192.168.1.2'])
@task('deploy', ['on' => ['web-1', 'web-2']])
cd /home/user/example.com
git pull origin {{ $branch }}
php artisan migrate --force
@endtask默认情况下，任务将在每台服务器上串行执行。换句话说，一个任务将在第一台服务器上运行完毕后，才会继续在第二台服务器上执行。如果您想在多台服务器上并行运行任务，请将 parallel 选项添加到任务声明中：
@servers(['web-1' => '192.168.1.1', 'web-2' => '192.168.1.2'])
@task('deploy', ['on' => ['web-1', 'web-2'], 'parallel' => true])
cd /home/user/example.com
git pull origin {{ $branch }}
php artisan migrate --force
@endtask有时，您可能需要在运行 Envoy 任务之前执行任意 PHP 代码。您可以使用 @setup 指令来定义一个 PHP 代码块，该代码块应在您的任务之前执行：
@setup
$now = new DateTime;
@endsetup如果您需要在任务执行前引入其他 PHP 文件，您可以在您的 Envoy.blade.php 文件的顶部使用 @include 指令：
@include('vendor/autoload.php')
@task('restart-queues')
# ...
@endtask如果需要，您可以通过在调用 Envoy 时在命令行上指定参数来向 Envoy 任务传递参数：
php vendor/bin/envoy run deploy --branch=master你可以使用 Blade 的 "echo" 语法来访问任务中的选项。你还可以在任务中定义 Blade 的 if 语句和循环。例如，让我们在执行 git pull 命令之前验证 $branch 变量的存在性：
@servers(['web' => ['user@192.168.1.1']])
@task('deploy', ['on' => 'web'])
cd /home/user/example.com
@if ($branch)
git pull origin {{ $branch }}
@endif
php artisan migrate --force
@endtask故事将一组任务归类在一个单一、方便的名称下。例如，一个deploy故事可能会通过在其定义中列出任务名称来运行update-code和install-dependencies任务：
@servers(['web' => ['user@192.168.1.1']])
@story('deploy')
update-code
install-dependencies
@endstory
@task('update-code')
cd /home/user/example.com
git pull origin master
@endtask
@task('install-dependencies')
cd /home/user/example.com
composer install
@endtask一旦故事已写好，你就可以像调用任务一样调用它：
php vendor/bin/envoy run deploy当任务和故事运行时，多个钩子会被执行。Envoy支持的钩子类型有@before，@after，@error，@success，以及@finished。这些钩子中的所有代码都被解释为PHP并在本地执行，而不是在你的任务与之交互的远程服务器上。
您可以根据需要定义任意数量的这些钩子。
它们将按照在您的 Envoy 脚本中出现的顺序执行。
@之前在每次任务执行之前，所有在你的 Envoy 脚本中注册的 @before 钩子都将执行。@before 钩子会接收即将执行的任务名称：
@before
if ($task === 'deploy') {
// ...
}
@endbefore@after每次任务执行后，在你的 Envoy 脚本中注册的所有 @after 钩子都将执行。 @after 钩子接收已执行任务的名称：
@after
if ($task === 'deploy') {
// ...
}
@endafter@错误每次任务失败后（以大于 0 的状态码退出），所有在您的 Envoy 脚本中注册的 @error 钩子都将执行。@error 钩子会接收已执行任务的名称：
@error
if ($task === 'deploy') {
// ...
}
@enderror@成功如果所有任务都已无错误执行，您的 Envoy 脚本中注册的所有 @success 钩子都将执行：
@success
// ...
@endsuccess@已完成在所有任务执行完毕后 (无论退出状态如何)，所有的 @finished 钩子都将被执行。@finished 钩子会接收到已完成任务的状态码，该状态码可能是 null 或一个大于或等于 0 的 integer：
@finished
if ($exitCode > 0) {
// There were errors in one of the tasks...
}
@endfinished若要运行在应用程序的 Envoy.blade.php 文件中定义的任务或故事, 请执行 Envoy 的 run 命令, 并传入要执行的任务或故事的名称. Envoy 将执行该任务, 并在任务运行时显示远程服务器的输出:
php vendor/bin/envoy run deploy如果您希望在您的服务器上运行给定任务之前收到确认提示，您应该将 confirm 指令添加到您的任务声明中。此选项对于破坏性操作特别有用：
@task('deploy', ['on' => 'web', 'confirm' => true])
cd /home/user/example.com
git pull origin {{ $branch }}
php artisan migrate
@endtaskEnvoy 支持在每个任务执行后向 Slack 发送通知。该 @slack 指令接受一个 Slack hook URL 和一个频道/用户名。您可以通过在您的 Slack 控制面板中创建一个“Incoming WebHooks”集成来检索您的 webhook URL。
你应该将完整的 webhook URL 作为传递给 @slack 指令的第一个参数。传递给 @slack 指令的第二个参数应该是一个频道名称 (#channel) 或一个用户名 (@user):
@finished
@slack('webhook-url', '#bots')
@endfinished默认情况下，Envoy 通知将向通知通道发送一条描述已执行任务的消息。但是，您可以通过传递第三个参数给 @slack 指令，来用您自己的自定义消息覆盖此消息：
@finished
@slack('webhook-url', '#bots', 'Hello, Slack.')
@endfinishedEnvoy 也支持在每次任务执行后向 Discord 发送通知。@discord 指令接受一个 Discord 钩子 URL 和一条消息。您可以通过在“服务器设置”中创建一个“Webhook”并选择该 webhook 应该发布到哪个频道来获取您的 webhook URL。您应该将完整的 Webhook URL 传入 @discord 指令中：
@finished
@discord('discord-webhook-url')
@endfinishedEnvoy 也支持在每个任务执行后发送通知到 Telegram。 @telegram 指令接受一个 Telegram 机器人 ID 和一个聊天 ID。 你可以通过使用 BotFather 创建新机器人来获取你的机器人 ID。 你可以使用 @username_to_id_bot 获取一个有效的聊天 ID。 你应该将完整的机器人 ID 和聊天 ID 传递给 @telegram 指令：
@finished
@telegram('bot-id','chat-id')
@endfinishedEnvoy 也支持在每次任务执行后发送通知到 Microsoft Teams。@microsoftTeams 指令接受一个 Teams Webhook（必需）、一条消息、主题颜色（success、info、warning、error）和一个选项数组。您可以通过创建一个新的 传入 webhook 来检索您的 Teams Webhook。Teams API 还有许多其他属性可用于自定义您的消息框，例如标题、摘要和部分。您可以在 Microsoft Teams 文档 上找到更多信息。您应该将完整的 Webhook URL 传入 @microsoftTeams 指令中：
@finished
@microsoftTeams('webhook-url')
@endfinished