hyperf测试环境需设app_env=testing和app_debug=true以显示详细异常;检查异常处理器未被覆盖、无中间件静默错误,并通过故意抛异常接口验证html/json错误页及日志输出。

Hyperf 默认在生产环境会隐藏详细错误信息,防止敏感数据泄露;但在测试或开发阶段,需要快速看到完整的异常堆栈和上下文。切换测试环境并展示接口异常信息,关键在于两处配置:应用环境标识 + 异常处理器行为。
确认当前是测试环境
Hyperf 通过 APP_ENV 环境变量区分环境。确保你的 .env 文件中已设置:
APP_DEBUG=true
这两项缺一不可:APP_ENV=testing 触发框架加载测试专用配置(如日志、异常处理),APP_DEBUG=true 允许框架在响应中输出详细错误信息(包括文件、行号、变量 dump)。
检查异常处理器是否启用调试模式
Hyperf 使用 Hyperf\ExceptionHandler\ExceptionHandler 处理未捕获异常。在测试环境下,它应自动返回 HTML 或 JSON 格式的详细错误页。若仍只返回简单 500,需确认:
- config/autoload/exceptions.php 中未覆盖默认异常处理器,或已显式启用
debug模式 - 没有自定义中间件提前拦截并静默了异常(例如 catch-all try-catch 或全局错误捕获逻辑)
- HTTP 服务未启用
display_errors(虽协程下不依赖 PHP ini,但某些底层错误仍受其影响)
触发并验证异常展示效果
写一个故意出错的接口来测试:
#[Controller]
#[GetMapping("/debug/error")]
public function triggerError()
{
throw new RuntimeException('测试环境异常已触发');
}
访问该接口后,应看到带堆栈、协程 ID、请求 ID 的完整错误页面(HTML)或结构化 JSON(取决于 Accept 头)。若只显示空白或 {"status":500},说明 APP_DEBUG=false 或异常被中间件吞掉。
日志中同步输出异常详情
即使接口返回简化信息,测试环境的日志也应记录完整异常。Hyperf 默认将异常写入 runtime/logs/hyperf.log,且每条日志含协程 ID 和 trace。确保 config/autoload/logger.php 中 'default' => 'std' 日志驱动启用,并未禁用 level: 'debug'。










