开发时应禁用hyperf异常处理器以显示php原生错误:清空config/autoload/exceptions.php中的handler配置,确保display_errors=on和error_reporting=e_all,并检查swoole与php错误日志。

Hyperf 默认的异常处理机制会捕获未捕获的异常并返回统一格式的响应(如 JSON 错误信息),但有时你希望在开发阶段直接显示 PHP 原生错误堆栈(比如 Whoops 或 Xdebug 的调试界面),便于快速定位代码运行错误。这需要修改异常处理配置,**关闭 Hyperf 的全局异常处理器**或**调整其行为**,让底层错误透出。
确认当前异常处理器是否启用
Hyperf 通过 ExceptionHandler 组件接管所有未捕获异常。检查你的项目中是否注册了自定义异常处理器(如 App\Exception\Handler\AppExceptionHandler),并在 config/autoload/exceptions.php 中启用:
- 若该文件存在且包含类似
'handler' => [App\Exception\Handler\AppExceptionHandler::class],说明异常被拦截 - 若使用默认配置(无自定义 handler),Hyperf 仍会使用框架内置的
Hyperf\ExceptionHandler\Handler\HttpExceptionHandler
开发环境临时禁用异常处理器
最直接的方式是让异常不被 Hyperf 捕获,从而触发 PHP 原生错误处理(如 Xdebug 的错误页面)。可在 config/autoload/exceptions.php 中清空 handler 配置:
return [
'handler' => [],
];
⚠️ 注意:此操作仅限本地开发环境,切勿在测试/生产环境使用。同时确保 display_errors = On 和 error_reporting = E_ALL 在 PHP 配置中已开启。
保留部分异常处理但透出运行时错误
如果仍需处理业务异常(如 ValidationException),但想让语法错误、Fatal Error 等底层问题直接暴露,可自定义一个更“宽松”的异常处理器:
- 继承
Hyperf\ExceptionHandler\Handler\HttpExceptionHandler - 重写
isValid方法,对ParseError、FatalError、Error等非Exception子类不做处理(直接 return false) - 在
config/autoload/exceptions.php中注册该 handler
这样,普通 throw new RuntimeException() 仍走 Hyperf 处理流程,而 undefined function xxx() 或 Class not found 类错误会直接报错。
检查 Swoole 错误日志与 PHP 错误日志
即使异常处理器被禁用,Swoole 进程也可能静默吞掉部分致命错误。建议同步检查:
-
storage/logs/hyperf.log中是否有PHP Fatal error记录 - PHP 错误日志路径(
php.ini中error_log配置)是否可写 - 启动服务时加上
--watch并观察终端输出,很多 ParseError 会在 reload 时直接打印到控制台











