如何便捷向控制台输出日志并调试Laravel Envoy Blade文件

为什么@setup块的echo不输出、只显示通用错误 #

Envoy 运行分为两个阶段：第一阶段是本地编译Blade模板，解析@setup、@servers的PHP逻辑，生成最终要执行的任务脚本；第二阶段才是通过SSH连接对应服务器执行任务。
默认情况下编译阶段的普通输出会被缓冲吞掉，同时Envoy默认关闭详细错误输出，所以只会返回通用的Whoops, looks like something went wrong提示，不会暴露具体错误位置。

开启完整错误提示 #

运行Envoy任务时追加最高级别的verbose参数，即可输出完整异常栈、SSH连接详情、编译过程日志，不再只显示通用错误：

envoy run 你的任务名 -vvv

同时可以在@setup块最开头强制开启PHP错误显示，直接定位语法错误、未定义变量等问题：

@setup
error_reporting(E_ALL);
ini_set('display_errors', 1);
// 其余配置代码
@endsetup

控制台输出调试日志的正确写法 #

• 针对@setup块（本地编译阶段运行的PHP代码）：不要用普通echo，直接向标准输出流写入内容即可正常打印到控制台：

@setup
// ... 你的配置逻辑
// 打印普通文本
fwrite(STDOUT, "Deploy started\n");
// 打印变量内容
fwrite(STDOUT, "[调试] 当前SSH参数：".var_export($sshOptions, true)."\n");
fwrite(STDOUT, "[调试] 目标服务器：".var_export($server, true)."\n");
@endsetup

• 针对@task块（远程/本地服务器执行的脚本）：直接写PHP的echo或shell的echo命令即可，输出会自动回传到控制台，也可以直接通过Blade插值打印编译阶段生成的变量：

@task('debug:config', ['on' => 'localhost'])
echo "当前SSH配置：{{ $sshOptions }}"
echo "目标服务器：{{ $server }}"
@endtask

写完直接运行envoy run debug:config就能快速查看所有配置变量的实际取值，不需要靠抛异常传递信息。

逐行调试定位故障的技巧 #

• 调试阶段先把@servers里的目标机器临时改成localhost，先在本地跑通@setup块的配置逻辑，再切换到远程服务器，排除SSH连接、权限类的干扰问题。
• 遇到语法错误时直接去系统临时目录（通常是/tmp路径）找Envoy生成的临时编译文件（文件名带envoy和随机字符串后缀的PHP文件），直接查看编译后的代码对应行号，就能快速定位是Blade语法问题还是原生PHP逻辑错误。
• 排查SSH连接字符串错误时，开-vvv参数后会打印实际拼接完成的SSH执行命令，直接把命令复制到本地终端运行，就能快速定位引号转义、参数缺失类问题。

常见触发通用错误的场景 #

• @servers块引用的变量没有在它之前的@setup块中定义，Envoy按顺序编译模板，后置定义的变量无法被前置的@servers块读取。
• SSH连接字符串的引号转义错误，比如拼接参数时多写/少写了转义双引号，导致生成的SSH命令格式非法。
• @setup块中调用了未引入的类、未定义的函数，且没有开启详细报错的情况下会直接触发通用错误提示。

内容的提问来源于stack exchange，提问作者Alex