hyperf启动失败的第一手线索是终端启动日志，需重点关注[error]/[warn]、php fatal error及class not found等行；默认实时输出于php bin/hyperf.php start终端，若无输出则可能崩溃于前置步骤，docker需加-it参数，生产环境可用nohup并tail -f追踪。
Hyperf 启动失败时，第一手线索就在启动日志里。别跳过它，直接看终端输出的原始信息，尤其是 [ERROR]、[WARN] 和带 PHP Fatal error 或 Class not found 的行——这些不是干扰项，而是定位问题的起点。
启动日志默认在哪看
执行 php bin/hyperf.php start 后，所有初始化过程（包括配置加载、组件注册、服务监听）都会实时打印在终端。这是最权威的“启动快照”，无需额外配置就能看到。
- 如果终端没输出或一闪而过，说明进程已崩溃退出，此时要立刻检查是否卡在前置步骤（比如
Zend MM unknown error） - 若使用 Docker，必须加
-it参数运行容器，并确保日志不被重定向（如没写> /dev/null） - 生产环境建议保留终端输出，同时用
nohup php bin/hyperf.php start &启动后，用tail -f nohup.out追踪
关键错误类型与对应日志特征
不同层级的问题，在日志中表现差异明显，快速识别能省下大量排查时间：
-
端口占用：出现
failed to listen server port [0.0.0.0:9501], Error: Address already in use [98]—— 立即查lsof -i :9501 -
扩展缺失：报
Class 'Swoole\Http\Server' not found或Class 'Swow\Socket' not found—— 检查php --ri swoole或php --ri swow -
短名称冲突：只显示
Segmentation fault或Zend MM unknown error，无堆栈 —— 执行php -r "var_dump(function_exists('go'));"，返回true就必须关swoole.use_shortname -
配置中心阻塞：日志停在
Loading config from Nacos...或长时间无响应 —— 临时设CONFIG_CENTER_ENABLE=false验证 -
注解/路由异常：报
Controller annotation cannot be repeated或启动后curl返回 404 —— 检查#[Controller]是否重复，或prefix末尾多写了/
让日志更清晰：启用调试模式
加 --debug 参数可展开隐藏细节，尤其对组件初始化顺序、依赖注入链路非常有用：
- 运行
php bin/hyperf.php start --debug - 你会看到每一步加载了哪些配置文件、哪些类被实例化、哪些监听器被触发
- 若报
Swoole eventLoop already created，debug 日志会明确指出是哪个自定义进程或 Boot 类提前触发了 EventLoop - 注意：不要长期开启 --debug，它会影响性能，仅用于故障定位
日志内容不可见？检查三个硬性前提
有时候不是没日志，而是被静默吞掉了：
- runtime/logs 目录不可写：虽然不影响启动，但会导致部分组件（如 logger 初始化失败）的日志无法落盘，表现为“什么都没打出来”
-
CLI PHP 配置未生效：改了
php.ini却忘了 CLI 读的是php-cli.ini，执行php --ini确认路径 -
错误报告级别被压制：检查
error_reporting和display_errors是否为On，尤其在 Docker 中常被默认关掉
