Hyperf启动失败首要原因是Swoole运行环境未达标：必须确保CLI下php -m显示swoole、版本4.8.0～5.1.x、openssl与http2启用，且swoole.use_shortname=Off（验证function_exists('go')为false），同时修复runtime/storage权限及vendor/bin/hyperf.php执行权限。
Hyperf 启动时报服务运行错误，多数不是配置写错了，而是 Swoole 运行环境没达标或关键参数冲突。重点不在“怎么配”，而在“配之前是否已满足硬性前提”。
必须先确认 Swoole 扩展已正确加载
Hyperf 启动失败的第一道门槛是 Swoole 扩展缺失或未启用。报错如 Class 'Swoole\Http\Server' not found 就说明 CLI 环境根本没加载 Swoole。
- 执行
php -m | grep swoole，输出必须有swoole；若无，检查php --ini显示的主配置文件路径，在对应php.ini或php-cli.ini末尾添加extension=swoole（源码编译则写extension=swoole.so） - 执行
php -r "echo Swoole\VERSION;"，版本需为 4.8.0～5.1.x（避开 5.0.0～5.0.3 的已知协程调度 bug） - 执行
php --ri swoole，确认enable openssl → true且enable http2 → true；任一为 false 都会导致 HTTPS/gRPC 功能异常甚至启动卡死
swoole.use_shortname = Off 是强制要求
只要开启短函数名（go()、chan()），Zend 内存管理器就会被污染，直接触发 Zend MM unknown error 崩溃——不报堆栈、不提示位置，只 segfault。
- 在 CLI 和 FPM 对应的 php.ini 中都添加：
swoole.use_shortname = Off（注意是= Off，不是= 'Off'或= 0） - 验证方式：
php -r "var_dump(function_exists('go'));"必须返回bool(false) - 宝塔用户注意：进「PHP 设置 → 安装扩展」页，Swoole 行右侧必须显示
Short Name: Off；勾选扩展不等于关闭短名
server.php 中常见参数陷阱
配置本身语法正确，但某些值会与 Swoole 版本或系统限制冲突，导致静默失败或启动后无法响应。
-
port必须是整数，不能是字符串"9501"，否则 Swoole 会忽略监听 -
host若设为'127.0.0.1'，Nginx 在宿主机代理时需确保proxy_pass指向该地址；若部署在 Docker，Nginx 无法直连容器内127.0.0.1，应改用容器名或host.docker.internal -
options['hook_flags']如设为SWOOLE_HOOK_ALL，旧版 Swoole 可能不支持全部钩子，引发内存错乱；可先注释该行测试 -
worker_num不宜过大（如 >100），尤其在低内存机器上，易触发 OOM 或进程被系统 kill
权限与运行时目录问题常被误判为配置错误
错误日志里出现 Permission denied，90% 是 runtime/、storage/ 或 vendor/bin/hyperf.php 权限不对，而非 server.php 写错了。
- 用
ps aux | grep swoole查看实际运行用户（如www-data），再执行ls -ld runtime storage确认属主匹配 - 不匹配就修复：
sudo chown -R www-data:www-data runtime storage -
vendor/bin/hyperf.php必须有执行权限：chmod +x vendor/bin/hyperf.php - 清空残留缓存：
rm -rf runtime/*，再启动
