Hyperf启动报错需分层排查：先用--debug显式输出启动流程与异常堆栈，再查runtime/logs/hyperf.log定位ERROR/CRI-TICAL线索，同步验证server.php与exceptions.php的name键一致性、AOP代理生成、进程注册及Redis/MySQL/Swoole等底层依赖是否就绪。
Hyperf 启动报错时，启用调试环境不是加个--debug就完事，关键在于让错误“显形”——既要看到原始异常，又要准确定位到哪一层出了问题。默认环境下很多错误被静默吞掉或堆栈被协程截断，必须主动打开几道“闸门”。
启动时强制开启调试模式
直接运行带--debug参数的命令：
-
php bin/hyperf.php start --debug：框架会输出更详细的启动流程、组件加载顺序及首次异常堆栈 - 若仍看不到完整错误，加
--verbose（部分版本支持）或改用php -d display_errors=1 bin/hyperf.php start --debug确保PHP层错误不被屏蔽 - 注意：
--debug只对启动阶段生效，运行中异常需靠日志和异常处理器配合
检查错误日志源头
别只盯着控制台，Hyperf 的真实错误往往藏在日志文件里：
- 默认日志路径为
runtime/logs/hyperf.log，打开后从末尾往前翻，找[ERROR]或[CRITICAL]行 - 常见线索包括：
Class not found（扩展缺失）、Address already in use（端口占用）、Connection refused（Redis/MySQL未就绪）、Permission denied（目录权限问题） - 如果日志为空，说明错误发生在日志系统初始化之前——这时
--debug输出就是唯一依据
验证配置与注解是否合法
很多启动失败源于配置错位或注解冲突，这类问题不抛异常但阻塞启动：
- 检查
config/autoload/server.php中name字段是否与exceptions.php里的handler键名完全一致（大小写敏感） - 运行
php bin/hyperf.php gen:proxy看是否报错，能快速暴露AOP代理类生成失败（如注解重复、类型提示错误） - 临时注释掉
processes.php中非核心进程（如ConsumerProcess），排除初始化顺序冲突
确认底层依赖是否就绪
Hyperf 启动失败常卡在依赖服务连接环节，需逐项验证：
- Redis：执行
redis-cli -h 127.0.0.1 -p 6379 ping，再在控制器里调用$this->container->get(\Hyperf\Contract\ConnectionInterface::class)->ping() - MySQL：用
mysql -h 127.0.0.1 -u root -p -e "SELECT 1"测试，同时检查config/autoload/databases.php中pool.max_connections是否足够 - Swoole/Swow扩展：运行
php --ri swoole或php --ri swow，确认版本与Hyperf兼容（如Hyperf 3.1需Swoole ≥ 5.0.3）
