hyperf常见问题集中在环境配置、路由与控制器、数据库连接、静态资源、定时任务和内存管理；需确保php≥7.2、swoole启用、正确配置路由与控制器继承关系、合理设置数据库连接池参数、开启静态资源处理并规范nginx代理规则。
Hyperf 常见问题大多集中在环境配置、路由与控制器、数据库连接、静态资源、定时任务和内存管理这几个环节。只要抓住关键配置点和运行机制，多数故障能快速定位并修复。
环境与启动类问题
启动失败、命令报错、Worker0 内存飙升，常源于基础依赖缺失或配置冲突。
- 确保 PHP 版本 ≥ 7.2，Swoole 扩展已安装且启用（php -m | grep swoole 验证）；
- 启动前执行 composer install --no-dev，避免开发依赖干扰生产环境；
- Worker0 内存异常高，优先检查是否有未释放的协程、全局静态变量或未 close 的 Mutex 锁；
- 使用 php bin/hyperf.php server:watch 启动热更新模式辅助调试，但生产环境务必关闭。
路由与控制器不生效
访问 404、方法无响应，多因路由注册遗漏或命名空间错误。
- 确认 routes/routes.php 中已显式调用 Router::get/post(...)，且控制器类路径与命名空间完全匹配；
- 控制器必须继承 Hyperf\HttpServer\Controller，方法需为 public，返回值建议用 $this->response->json() 或 success()；
- 若用 Hyperf Nano，路由直接写在 index.php 中，无需 routes.php 文件，闭包方式定义即可；
- 清空 runtime/container 和 runtime/cache 目录后再启动，排除容器缓存干扰。
数据库连接与查询异常
“Too many connections”、“MySQL server has gone away”、“Connection timeout”，本质是连接池或网络层配置不合理。
- 检查 config/autoload/db.php 中 pool.max_connections 是否过小（建议 50–100），pool.wait_timeout 和 pool.max_idle_time 是否设为 5.0 和 30.0；
- 事务未提交或异常未回滚会导致连接长期占用，Hyperf 在协程结束时会自动回滚未提交事务，但仍建议显式调用 $this->db->commit() 或 ->rollback()；
- 跨协程复用 PDO 实例不可行，所有 DB 操作必须在当前协程内完成；
- 用 SHOW PROCESSLIST 查看 MySQL 实时连接数，确认是否被外部脚本或监控工具持续占满。
静态资源与反向代理问题
Nginx 代理后 CSS/JS 加载 404、Swagger 文档无法访问，通常因路径映射或 Swoole 静态处理开关未开。
- 确认 config/autoload/server.php 中 enable_static_handler 为 true，document_root 指向 public/ 目录；
- Nginx 配置中，静态文件应由 Nginx 直接服务（location ~* \.(js|css|png)$ { root /path/to/public; }），动态请求才 proxy_pass 到 Swoole；
- Swagger JSON 文件输出路径（如 public/swagger/swagger.json）需确保目录可写，且该路径在 Nginx 的 root 范围内；
- 修改资源后浏览器仍加载旧版？检查是否启用了强缓存（Cache-Control: immutable），临时加版本号或禁用缓存调试。
