Laravel Envoy 是独立于 Laravel 的 SSH 任务运行工具，通过 Blade 风格语法定义远程部署等任务，仅支持 Mac/Linux，需手动配置 @servers、@task、@setup 等核心块，依赖本地 SSH 密钥认证与伪终端（pty）支持。
Envoy 不是 Laravel 框架内置组件，它是一个独立的、专为 SSH 远程任务设计的 CLI 工具，和 Laravel 项目本身无运行时依赖。你不需要在 Laravel 应用里 use 任何 Envoy 类，也不用注册服务提供者——它只在你本地终端运行，通过 SSH 连上服务器执行命令。
Envoy 初始化后生成的 Envoy.blade.php 文件怎么写
初始化命令 envoy init vagrant@192.168.1.1 会生成一个基础模板，但默认内容极简，几乎不能直接用。你需要手动补全三块核心：
-
服务器定义：用
@servers块声明目标机器，支持数组和分组，例如：@servers(['web' => 'deploy@192.168.1.10', 'db' => 'deploy@192.168.1.11'])
-
任务定义：用
@task包裹要执行的 shell 命令，注意每行命令需以分号结尾（Blade 解析需要），例如：@task('deploy', ['on' => 'web'])cd /var/www/myapp && git pull origin main && composer install --no-dev --optimize-autoloader && php artisan migrate --force@endtask -
本地前置/后置逻辑：用
@setup和@done处理本地动作（比如校验 Git 状态、发送 Slack 通知），它们不走 SSH，只在本机执行
别漏掉 @option —— 它能让你传参，比如 envoy run deploy --branch=staging，然后在 @setup 里用 $branch 变量接住。
为什么 envoy run deploy 报错 “Permission denied (publickey)”
这不是 Envoy 的 bug，而是 SSH 密钥认证没通。Envoy 底层调用的是系统 ssh 命令，它完全复用你的本地 SSH 配置。
- 先确认
ssh deploy@192.168.1.10能直连成功；如果不行，Envoy 必然失败 - 检查私钥权限是否为
0600：chmod 0600 ~/.ssh/id_rsa，否则 OpenSSH 会拒绝加载 - 如果你用了非默认密钥（比如
id_rsa_deploy），必须在@servers里显式指定：@servers(['web' => ['user' => 'deploy', 'host' => '192.168.1.10', 'key' => '~/.ssh/id_rsa_deploy']])
- 别把密码写进
Envoy.blade.php—— Envoy 不支持密码登录，只认密钥或 SSH agent
远程命令执行一半卡住，或者 artisan migrate 没反应
本质是远程 shell 缺少交互式 TTY，导致某些命令（尤其是带提示、sudo、或需要终端尺寸的）直接挂起。
- 加
@option('pty' => true)到@task声明里，强制分配伪终端：@task('deploy', ['on' => 'web', 'pty' => true]) - 避免在任务里写
sudo service nginx reload这类需要密码的命令；要么配好 NOPASSWD，要么改用无特权操作 - 长命令（如
composer install）建议重定向输出：composer install --no-dev > /dev/null 2>&1，否则大量输出可能触发 Envoy 内部缓冲区截断 - 不要在
@task里用cd切换目录后跟多条命令——每行cd是独立 shell，下一行又回到初始路径；改用cd /path && command1 && command2
Envoy 能否替代 phpseclib 或 laravel-remote
不能混用场景。Envoy 是纯本地 CLI 工具，面向部署脚本这类“人手一敲就跑”的一次性任务；而 phpseclib 是 PHP 库，适合嵌入到 Web 请求或队列中动态执行；laravel-remote 则是 Laravel 命令封装，走 Artisan 接口，支持环境切换和确认交互。
- 如果你需要在 CI 流水线里自动触发部署，Envoy 最轻量、最可控
- 如果你要在后台任务里根据数据库状态决定是否执行
artisan queue:restart，就得用phpseclib封装连接逻辑 - Envoy 的
@task不支持返回结构化数据（比如捕获git status输出做判断），这种动态分支逻辑必须交给 PHP 层处理
真正容易被忽略的是：Envoy 没有内置重试、超时熔断或并发控制。一个 @task 卡死，整个 envoy run 就卡住，且不会自动 kill 远程进程。生产级部署建议用 Ansible 或自研调度器兜底，Envoy 更适合作为开发侧快速验证的胶水层。
