hyperf 是基于 swoole 的 php 协程框架，需在 linux 环境中配合 php≥8.1、swoole≥5.1.1、opcache.enable_cli=0 及 composer≥2.5 运行；四步完成：确认环境、创建项目并安装 http-server、编写带 prefix 注解的控制器、验证路由。
Hyperf 不是 Linux 发行版，也不能“装进”系统里——它是一个基于 Swoole 的 PHP 协程框架，必须在已有 Linux 环境（如 Ubuntu 22.04 或 CentOS 7/8）中，配合正确版本的 PHP 和扩展才能运行。新手卡住，90% 是因为环境没配对、扩展没加载或启动步骤跳步。下面直奔主题，四步到位。
确认基础环境是否达标
Hyperf 3.x 要求明确且严格，不达标会静默失败或报错退出：
- 运行 php -v，确保 PHP ≥ 8.1（Ubuntu 默认源常带旧版，推荐加 PPA：
sudo add-apt-repository ppa:ondrej/php && sudo apt update） - 运行 php --ri swoole，检查两行关键输出：
coroutine => enabled和Version => 5.1.1（或更高） - 编辑 php.ini（CLI 配置，非 FPM），确保
opcache.enable_cli=0已显式设置——这是协程崩掉最常见原因 - 运行 composer --version，要求 ≥ 2.5；若旧，用官方命令升级：
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"→php composer-setup.php
创建项目并装上 HTTP 服务组件
骨架本身不带 Web 能力，漏掉这步会导致 start 后无端口监听、curl 直接超时：
- 执行：
composer create-project hyperf/hyperf-skeleton myapp - 进入目录：
cd myapp - 必须安装：
composer require hyperf/http-server（不是可选，是必需） - 首次启动前建议手动触发依赖注入代理生成：
php bin/hyperf.php di:generate
写一个能跑通的控制器
别抄错注解格式，prefix 写法和命名直接影响路由是否命中：
- 在
app/Controller/下新建IndexController.php - 内容严格按如下写（注意
prefix: '/api'不带尾部斜杠）：
use Hyperf\HttpServer\Annotation\AutoController;
#[AutoController(prefix: '/api')]
class IndexController {
public function index() {
return ['status' => 'ok', 'timestamp' => time()];
}
}
- 保存后执行：
php bin/hyperf.php start，默认监听127.0.0.1:9501 - 访问
http://127.0.0.1:9501/api/index应返回 JSON
验证与排错小技巧
启动成功 ≠ 路由生效，快速确认是否真通：
- 查注册路由：
php bin/hyperf.php route:list，输出中应含GET | /api/index | App\Controller\IndexController::index - 临时重命名控制器文件（如改为
IndexController.php.bak），再 curl 同一地址，应返回 404 —— 这说明原路由确实被框架识别了 - 若提示
Class not found，先清缓存：rm -rf runtime/ di/，再chown -R $USER:$USER .确保权限，最后重试di:generate - 若
php -m | grep swoole无输出，检查swoole.so路径是否真实存在，并在 php.ini 中用绝对路径加载：extension=/usr/lib/php/20220829/swoole.so
