Envoy 是 SSH 任务编排器而非部署工具；必须包含 @servers（关联数组，键名供 @task 的 on 参数匹配）和 @task（定义 Bash 命令流），且需用 set -e 防止错误继续执行，避免静默失败。
Envoy 不是部署工具，它是 SSH 任务编排器 —— 能不能可靠部署，取决于你怎么写命令、怎么处理失败、怎么控制执行顺序。
Envoy.blade.php 文件结构必须包含 @servers 和 @task
缺一不可，否则
会报错或静默退出。@servers 定义连接目标，@task 定义要执行的 Bash 命令流。
必须是关联数组，键名（如
）会在
的
参数里复用；值必须是完整 SSH 地址，比如
或带端口的
的
参数值必须严格匹配
中定义的键名；如果写成
但
里只有
，任务不会报错，但也不会执行任何命令
不支持在
内部直接写 PHP 逻辑（比如
判断），所有条件分支都得靠 Bash 实现，或者用
提前计算变量再传入
部署脚本里 git pull 失败时默认不中断，得手动加 set -e
Envoy 默认用
执行每条命令，而
遇到错误不会自动退出 —— 这意味着
失败后，后续的
仍会照常运行，极易导致部署污染。
在
开头显式加上
，让任意命令失败立即终止整个任务
如果某条命令允许失败（比如
在非维护状态可能报错），改用
别依赖
拼接，
更简洁且覆盖所有子命令（包括管道中的）
多服务器并行部署时，--parallel 参数和 task 上的 parallel=>true 不能共存
命令行传
和任务定义里写
是两套互斥机制。混用会导致 Envoy 忽略并行设置，退化为串行执行，且不报错。
想全局启用并行：删掉所有
中的
键，只在运行时加
想固定某个任务必须并行：在
数组中保留
，运行时不要加
并行模式下，各服务器输出会交错打印，无法保证顺序；若需日志隔离，得在脚本里重定向到不同文件，比如
envoy run 报 SSH connection failed 的真实原因往往不是网络
绝大多数
错误其实源于本地环境配置缺失，而非远程服务器 SSH 服务异常。
确认
在
中，否则
命令根本找不到（常见于 macOS M1/M2 新装 Homebrew 后未更新 shell 配置）
检查本地
是否能直连目标服务器：
；如果提示输入密码，说明公钥没配好，Envoy 也必然失败
Envoy 不读取
中的别名或 ProxyJump 配置，所有连接参数必须硬编码在
值里，例如
真正难处理的从来不是语法，而是部署过程中那些“应该成功但没成功”的静默失败：迁移没跑、缓存没清、队列没重启。Envoy 只负责发命令，不负责验证结果 —— 每一步是否生效，得你自己加
或
这类校验命令来兜底。
envoy run@servers'web'@taskon'user@192.168.1.10''deploy@prod.example.com:2222'@taskon@serverson => 'web-server'@servers'web'@taskif@setup/bin/shshgit pullcomposer install@taskset -ephp artisan downphp artisan down || true|| exit 1set -e--parallel['parallel' => true]@taskparallelenvoy run deploy --parallel@task'parallel' => true--parallel> /tmp/deploy-{{ $server }}.log 2>&1SSH connection failed~/.composer/vendor/bin$PATHenvoysshssh user@host~/.ssh/config@servers'user@host -o ProxyJump=jump-host'ls -l storage/framework/cachephp artisan is-up