Hyperf 生产环境下默认隐藏错误堆栈，需设 APP_DEBUG=true（即使 APP_ENV=prod）以显示详情，但仅限本地或白名单IP；注意检查自定义异常处理器、Nginx error_page 及 Swoole 配置，并严禁公网长期开启。
Hyperf 在生产模式（APP_ENV=prod）下默认会隐藏详细错误堆栈，只返回通用错误页或空响应，这对线上环境安全有利，但开发调试时反而阻碍问题定位。要让错误信息正常显示，关键不是“关闭生产模式”，而是调整错误处理行为——既可临时切回开发环境，也可在保持 prod 的前提下显式开启错误详情。
确认当前环境与错误配置
先检查 .env 文件中的核心配置：
-
APP_ENV=prod—— 决定是否启用生产级行为（如缓存、日志级别、错误隐藏） -
APP_DEBUG=false—— 真正控制错误详情是否暴露给客户端；设为true后，即使APP_ENV=prod，也会输出异常堆栈（但仅限本地 IP 或白名单 IP，取决于中间件逻辑） -
HYPERF_ERROR_HANDLER_SHOW_ERROR=true（Hyperf ≥ 3.1）—— 部分版本支持该独立开关，强制开启错误页面渲染
快速启用错误详情的两种方式
推荐优先使用以下任一方法，无需修改环境变量：
- 将
.env中的APP_DEBUG=true，然后重启服务（php bin/hyperf.php start） - 启动时临时覆盖：运行
APP_DEBUG=true php bin/hyperf.php start，不改动文件，适合测试后快速还原
注意中间件和 HTTP 层拦截
即使开启 APP_DEBUG，若项目自定义了全局异常处理器（如继承 AbstractExceptionHandler），或配置了 error_page 指令（Nginx 层），仍可能屏蔽原始错误。需检查：
-
app/Exception/Handler/下的处理器是否调用了$response->withStatus(500)->withBody(...)而未透出异常内容 - Nginx 配置中是否有
fastcgi_intercept_errors on;+error_page 500 /50x.html;类规则 - Swoole 的
http_compression或dispatch_mode异常时是否影响响应体输出
安全提醒：勿在公网环境长期开启 APP_DEBUG
APP_DEBUG=true 会直接向请求方暴露路径、类名、数据库配置片段等敏感上下文，极易被利用进行攻击探测。 仅建议用于：
- 本地开发机或内网测试环境
- 通过 SSH 端口转发访问的临时调试场景
- 配合 IP 白名单中间件（如判断
$request->getServerParams()['remote_addr'] === '127.0.0.1'）做条件性开启
