Hyperf 调试应按需控制而非简单隐藏：通过 APP_DEBUG 环境变量分级管理，开发设 true，生产强制 false；替换异常处理器实现非本地环境返回简洁 JSON 错误；用中间件按请求头或路由动态注入调试上下文；调试容器/AOP 问题时关闭注解与配置缓存。
Hyperf 默认开启调试模式时会暴露大量内部信息，但生产环境必须关闭，而开发中又需要高效定位问题。关键不是“隐藏”调试，而是按需控制调试信息的展示层级和触发条件。
调整 APP_DEBUG 环境变量控制全局行为
Hyperf 的调试开关核心是 APP_DEBUG，它直接影响异常页面、错误日志级别、配置缓存策略等。设为 false 时，框架不会渲染带堆栈的错误页，也不会记录 debug 级别日志，但依然会记录 error 级别日志供排查。
- 开发环境建议在 .env 中设为 APP_DEBUG=true，配合 APP_ENV=local
- 测试/预发环境可设为 APP_DEBUG=false，但通过自定义异常处理器保留部分上下文（如请求 ID、时间戳）
- 切勿在生产环境硬编码 APP_DEBUG=true，即使 .env 文件被误提交，也要靠部署脚本或 CI/CD 环节强制覆盖
禁用 Whoops 错误页面但保留结构化日志
Hyperf 基于 Hyperf\ExceptionHandler 组件处理异常，默认使用 Whoops 渲染友好错误页。若想“隐藏”前端可见的调试信息，又不想丢失诊断线索，可替换默认异常处理器：
- 新建自定义异常处理器，继承 ExceptionHandler，重写 render() 方法，对非本地环境返回统一 JSON 错误响应（如
{"code":500,"message":"Internal Server Error"}） - 在 config/autoload/exceptions.php 中注册该处理器，并确保只在 APP_ENV !== 'production' 时启用 Whoops
- 配合 Monolog 配置，在 config/autoload/logger.php 中为 debug 级别日志启用 LineFormatter，包含 trace_id 和 context 数据
按路由或中间件动态开启调试上下文
某些接口需临时查看完整请求/响应数据（如调试 WebSocket 握手或 gRPC 元数据），但又不能全局开调试。可通过中间件实现条件性增强日志：
- 编写一个 DebugContextMiddleware，检查请求头是否含 X-Debug-Context: true 或 query 参数 debug=1
- 命中时，将当前协程上下文注入 Logger::withContext()，添加 request_id、raw_body、headers 等字段
- 仅对特定路由组（如
/api/v1/debug/*）或管理员 IP 段启用该中间件，避免被滥用
关闭配置热更新与注解扫描缓存（仅开发机）
Hyperf 的 devtool 组件支持配置热更新和注解扫描缓存，提升开发体验，但可能掩盖配置加载顺序或注解解析问题。调试容器注入失败、AOP 不生效等场景时，可临时关闭：
- 在 config/autoload/devtool.php 中设 'scan_cacheable' => false，强制每次启动重新扫描注解
- 设 'publish_cacheable' => false，避免因缓存导致 config 文件未重载
- 执行 php bin/hyperf.php server:watch 时加 --no-cache 参数（需自定义命令支持）
