hyperf启动失败90%源于php或swoole版本/配置未对齐：php -v需≥8.1且php --ri swoole必须同时满足support coroutines=>enabled、version≥5.0、swoole.use_shortname=>off。

php -v 和 php --ri swoole 必须同时达标

Hyperf 启动失败，90% 是因为 PHP 或 Swoole 版本/配置没对齐。光看 php -v 显示 8.1 不代表真能用——它可能被系统多版本 PHP 干扰；光看 php -m | grep swoole 有输出也不保险——它可能是旧版非协程 Swoole。

必须执行这两条命令并逐项核对：

• php -v 输出第一行必须是 PHP 8.1. 或更高（如 8.2.15），不能是 8.0.x 或 7.4
• php --ri swoole 输出里必须同时满足：
  • support coroutines => enabled（不是 disabled）
  • version => 5.0. 或更高（如 5.1.3）
  • swoole.use_shortname => Off（不是 On）

常见坑：Ubuntu 自带的 php-swoole 包通常版本老旧且禁用协程，必须卸载后用 pecl install swoole 重装；Mac 上用 Homebrew 安装 PHP 时，需额外 pecl install swoole，默认不带。

composer create-project 后必须加 http-server

Hyperf 骨架项目默认不带 HTTP 能力——composer create-project hyperf/hyperf-skeleton 拉下来的只是个空壳，php bin/hyperf.php start 会静默监听但无端口响应，curl 直接超时。

进入项目目录后，立刻执行：

Hyperframes Creative

HyperFrames视频非动画创意指导，包括设计规范（frame.md/design.md）处理、配色、字体设计、旁白及节奏规划等。

下载

• composer require hyperf/http-server（不是 hyperf/websocket-server 或其他）
• 确认 config/autoload/server.php 中 'type' => 'http' 且 'port' => 9501 未被注释或改写
• 别跳过 composer dump-autoload，尤其改过命名空间或类名后

验证方式：启动后执行 ss -tlnp | grep :9501，应看到 php 进程监听；若无输出，说明 http-server 没生效或被覆盖。

AutoController 注解路由失效的三个硬性条件

写了 #[AutoController(prefix: '/api')] 却访问 404？不是代码写错，而是以下三者缺一不可：

• 控制器类文件必须放在 app/Controller/ 目录下（不是 app/Controllers/ 或 app/controller/）
• config/autoload/annotations.php 中 'paths' 必须包含 'app/Controller'，漏掉就扫描不到
• 开发环境务必设 'cacheable' => false，否则改了注解不重启服务不会刷新

别写 prefix: '/api/'（末尾斜杠），Hyperf 会拼出 /api//index 导致匹配失败；也别在方法里写 exit 或 die，协程会直接中断，后续请求全卡住。

Docker 环境里 swoole 扩展容易漏掉的一行命令

Alpine 或 Debian 基础镜像里装完 Swoole，常以为 extension=swoole.so 写进 php.ini 就完事——但 Alpine 下 pecl install swoole 不会自动启用，必须补一行：

• docker-php-ext-enable swoole（Dockerfile 里必须显式调用）
• 验证用 docker run --rm your-image php --ri swoole | grep "support coroutines"，输出 enabled 才算真正就绪
• 如果用 php:8.1-cli-alpine，记得先 apk add --no-cache $PHPIZE_DEPS，否则 pecl 编译失败静默跳过

本地开发没问题、Docker 里启动报 Swoole extension is not loaded，八成卡在这行没加。

php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！