hyperf 默认异常响应不包含完整堆栈信息，需自定义异常处理器：重写 app/exception/handler/exceptionhandler.php 的 render 方法，结构化输出 getmessage、getline、getfile、gettraceasstring；开发环境返回完整堆栈，生产环境隐藏敏感路径；统一返回 application/json，状态码按异常类型映射（如 validationexception→422）；启用 app_debug=true 和 hyperf_http_show_error=true；验证异常单独处理并标准化 errors 结构；可添加唯一 error_id 便于日志追踪。
Hyperf 默认的异常响应只返回简单错误信息，不包含完整的异常堆栈、文件位置和行号，不利于调试。要展示完整错误，需自定义异常处理器并配置 JSON 响应格式。
重写全局异常处理器
在 app/Exception/Handler/ExceptionHandler.php 中继承 Hyperf\ExceptionHandler\ExceptionHandler，重写 render 方法，将异常信息结构化输出：
- 捕获
Throwable，提取getMessage()、getLine()、getFile()、getTraceAsString() - 开发环境返回完整堆栈；生产环境隐藏敏感路径，仅保留简要错误 + 错误码
- 统一返回
application/json，状态码使用500（或按异常类型映射，如ValidationException→422）
启用调试模式并暴露详细错误
确保 .env 中已开启调试：
-
APP_DEBUG=true—— 启用 Hyperf 的调试支持 -
HYPERF_HTTP_SHOW_ERROR=true—— 允许 HTTP 层显示原始错误（配合自定义处理器生效） - 避免在生产环境开启，防止泄露路径、环境变量等敏感信息
补充：验证层异常单独处理
表单验证失败默认返回 422，但消息结构较扁平。可在 app/Exception/Handler/ValidationExceptionHandler.php 中统一格式化：
- 提取
$exception->validator->errors()->messages() - 包装为
"errors": {"field": ["message"]}标准结构 - 与全局异常响应保持字段一致，例如都含
code、message、trace（验证异常可设 trace 为空）
可选：添加异常唯一标识便于日志追踪
在响应中加入 request_id 或生成 error_id：
- 使用
uniqid('err_')或Str::uuid()生成唯一 ID - 记录到日志时带上该 ID，前端报错也可附带，方便后端快速定位日志上下文
- 注意不要在响应中暴露服务器内部路径、数据库连接等敏感字段
