Envoy 命令找不到是因 Composer 全局路径未加入 PATH：需将 ~/.composer/vendor/bin（Linux/macOS）或 %USERPROFILE%\AppData\Roaming\Composer\vendor\bin（Windows）添加至系统 PATH，并重载 shell 配置。
envoy 不是 Laravel 框架内置功能，它是个独立的 SSH 任务编排 CLI 工具，只在你本地终端运行，通过 SSH 连服务器执行命令。Mac/Linux 可用，Windows 不支持。
安装后 envoy 命令找不到？
这是 PATH 配置问题，不是 Envoy 安装失败。composer global require laravel/envoy 默认装到 ~/.composer/vendor/bin，但该路径没进你的 shell $PATH。
- 检查是否已加入：
echo $PATH | grep composer - 没输出？补上这行到你的 shell 配置文件（
~/.zshrc或~/.bash_profile）：export PATH="$HOME/.composer/vendor/bin:$PATH" - 重载配置：
source ~/.zshrc（或对应文件） - 验证：
which envoy应返回路径，envoy --version能正常输出
macOS M1/M2 新装 Homebrew 后常漏这步，别急着重装。
@servers 和 @task 怎么写才不白定义？
Envoy.blade.php 必须同时包含 @servers（关联数组）和至少一个 @task，否则 envoy run xxx 会静默退出或报错。
-
@servers的键名（如'web'）必须和@task的on参数值完全一致，大小写、下划线都不能错 - 值必须是完整 SSH 地址：
'user@host'、'deploy@192.168.1.10:2222'，或带密钥路径的数组：['user' => 'deploy', 'host' => '192.168.1.10', 'key' => '~/.ssh/id_rsa_prod'] -
@task内部每行 Bash 命令结尾要加分号（Blade 解析需要），且建议开头加set -e，否则git pull失败后composer install仍会执行 - 不支持在
@task里写 PHP 逻辑（比如@if），条件判断得靠 Bash 或提前在@setup里算好变量传入
远程命令卡住、php artisan migrate 没反应？
本质是远程 shell 缺少伪终端（PTY），导致需要交互或依赖 TTY 的命令挂起（比如带 sudo、php artisan down、或某些 Composer 插件）。
- 加
@option('pty' => true)到@task声明里：@task('deploy', ['on' => 'web', 'pty' => true]) - 别指望
ssh -t参数能透传——Envoy 不解析这个，必须显式声明pty - 启用
pty后，输出可能变乱（比如进度条闪烁），但命令能跑完；若需日志隔离，自己重定向：php artisan migrate --force > /tmp/migrate.log 2>&1
为什么 envoy run deploy 报 “Permission denied (publickey)”？
这不是 Envoy 的错，是 SSH 密钥链没通。Envoy 底层直接调用系统 ssh 命令，复用你本地全部 SSH 配置。
- 先手动测试：
ssh deploy@192.168.1.10—— 如果连不上，Envoy 必然失败 - 私钥权限必须是
0600：chmod 0600 ~/.ssh/id_rsa，OpenSSH 会拒绝加载其他权限的私钥 - 用了非默认密钥（如
id_rsa_staging）？必须在@servers里显式指定key字段，不能只靠~/.ssh/config - 别往
Envoy.blade.php里写密码——Envoy 不支持密码登录，只认密钥或已加载的 SSH agent
最易忽略的是：@servers 里写的 host 和用户，必须和你手动 ssh 命令里的一致；混用 root/deploy 用户、漏端口、或搞错域名别名，都会触发这个错误。
