Hyperf 启动失败需按系统层→PHP扩展层→框架配置层→业务代码层逐级排查：端口占用用lsof/netstat查PID并优先php bin/hyperf.php stop；Swow/Swoole扩展缺失或版本不兼容需按文档安装；注解重复、配置中心不可达、.env路径错误等配置问题需逐一验证；组件初始化顺序冲突或连接池依赖服务未就绪需加--debug分析。
Hyperf 启动失败通常不是单一原因导致的，而是由环境、配置、依赖或代码层面多个环节共同触发。核心思路是：先看错误类型，再定位层级（系统层 → PHP 扩展层 → 框架配置层 → 业务代码层），最后验证修复效果。
端口被占用或监听失败
典型报错：failed to listen server port [0.0.0.0:9501], Error: Address already in use [98]
- 执行
sudo lsof -i :9501或netstat -tulnp | grep :9501查进程 PID - 确认是否为残留的 Hyperf 进程（如未正常 stop 的 worker）、其他 PHP 服务、或本地调试工具（如 Xdebug 监听）占用了端口
- 避免直接 kill -9，优先用
php bin/hyperf.php stop停止服务；若无效再 kill 进程 - 开发中可临时改端口测试，修改
config/autoload/server.php中的port配置
扩展缺失或引擎不匹配
典型报错：Class "Swow\Socket" not found 或 Socket is closed(0)
- 使用 Swow 服务器但未安装 Swow 扩展：需编译安装 Swow，并确保
extension=swow.so已写入 php.ini -
Socket is closed(0)多因误启了假 Redis 服务（如 systemd 管理的 redisd），实际 Redis 并未运行，导致连接池初始化失败；应停用非标准 Redis 服务，改用官方包管理器安装（如 yum + remi 库） - Swoole 版本与 Hyperf 不兼容（如 Swoole 5.x 与 Hyperf 2.2 不适配），建议按官方文档指定版本安装
配置或注解冲突
典型报错：Controller annotation cannot be repeated 或 Client error: GET ... 404 Not Found
- 控制器中重复使用
#[Controller]注解（如前缀定义两次），只保留一个顶层路由前缀即可 - 启用 ACM/Nacos/Alibaba Config Center 但服务地址不可达或 dataId 不存在，会阻塞启动；可临时关闭
CONFIG_CENTER_ENABLE=false快速验证 -
.env文件路径错误（如Dotenv::createImmutable(__DIR__)在协程中工作目录变动），建议传入绝对路径：__DIR__ . '/../'
组件版本或初始化顺序问题
典型报错：Swoole eventLoop already created 或启动后无响应
-
hyperf/crontab升级到 3.0.9+ 后，内部初始化逻辑变更，可能与自定义进程、定时任务提前加载冲突；检查是否在ProcessManager或BootManager中过早调用了 crontab 相关类 - 多个协程服务器（如同时启用 HttpServer 和 WebSocketServer）共用同一 eventLoop 时，需确保监听地址和端口不重叠，且配置中
enable开关明确 - 某些组件（如
hyperf/database）依赖连接池，若数据库服务未就绪或配置错误，会导致启动卡在连接阶段，日志可能无明显报错，需加--debug启动观察
