hyperf 启动失败主因是核心扩展缺失或配置错误：必须启用 json、openssl、mbstring、pdo、bcmath、sockets、xml、pcntl 及 swoole（≥5.0）并设 swoole.use_shortname = off；redis 强烈推荐；所有扩展须在 cli 模式生效，而非仅 fpm。
Hyperf 运行不是“装了 PHP 就能跑”，缺任何一个核心扩展，php bin/hyperf.php start 要么直接报错退出，要么静默卡死、路由不响应、DB 查询超时——尤其在 PHP 8.1+ 下，漏掉 pcntl 或 swoole.use_shortname = Off 是最常见启动失败原因。
必须启用的硬性依赖扩展
以下扩展在 CLI 模式下必须启用，且版本/配置需对齐（以 Hyperf v3.x 为准）：
-
json、openssl、mbstring、pdo、bcmath、sockets、xml：PHP 自带，但需确认未被禁用（检查php -m | grep -E "(json|openssl|mbstring)"） -
pcntl：仅 Swoole 驱动必需，用于多进程管理；宝塔安装 PHP 时务必勾选，Ubuntu/Debian 需装php8.2-dev后编译 -
swoole≥ 5.0（或swow≥ 1.5）：必须启用协程支持，且php.ini中强制写入swoole.use_shortname = Off -
redis（可选但强烈推荐）：缓存、锁、消息队列、定时任务防重都依赖它；若不用 Redis，hyperf/crontab的mutex会退化为不可靠的file锁
常见错误现象与对应缺失项
这些报错基本能反向定位缺什么：
-
ERROR Swoole short function names must be disabled...→swoole.use_shortname = Off没写进php.ini，或改了文件但没重启 PHP 进程 -
Class 'Swoole\Coroutine' not found→ Swoole 扩展未加载，或版本 swoole.enable_coroutine = 1 未开启 - 服务启动无报错但 HTTP 请求无响应、
@GetMapping路由 404 →opcache.enable_cli = 1未关闭（CLI 模式下必须关） -
hyperf/crontab任务重复执行 →redis扩展缺失或config/autoload/redis.php配置错误，导致$mutex = ['type' => 'redis']失效
按场景补充的可选扩展
非运行必需，但业务一接入就立刻需要：
-
pdo_mysql或pdo_pgsql：数据库驱动，只装pdo不够，必须装对应数据库协议扩展 -
grpc+protobuf：gRPC 服务端/客户端通信必需 -
yaml：用于读取config/autoload/*.yml配置文件（Hyperf 默认用 PHP 数组，但团队协作常切 YAML） -
imagick或gd：图像处理类业务，非框架层依赖，但项目里大概率要用
最容易被忽略的是：所有扩展必须在 CLI 模式下生效。用宝塔或系统包管理器装完后，一定要验证 /www/server/php/81/bin/php -m（路径按你实际 PHP 版本调整），而不是只看 phpinfo() 网页版输出——后者反映的是 FPM 模式，跟 Hyperf 启动完全无关。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
