Hyperf 是 PHP 微服务协程框架，非 Linux 发行版；需在 Ubuntu 等系统部署 PHP ≥ 8.0、Swoole ≥ 5.0（启用协程）、禁用 opcache.enable_cli，通过 Composer 创建项目并启动，生产环境须配 Supervisor 或 systemd 守护。
Hyperf 不是 Linux 发行版，也不能“装进” Linux 系统里——它是一个 PHP 框架，必须在已有的 Linux 环境（如 Ubuntu 22.04）中，配合正确版本的 PHP 和 Swoole 才能运行。直接装错方向（比如搜“Hyperf ISO”或试图用 apt install hyperf）会卡死。
确认 PHP 和 Swoole 版本是否达标
Hyperf 3.x 要求 PHP ≥ 8.0、Swoole ≥ 5.0，且必须启用协程；低于这个组合，
php bin/hyperf.php start 会报错或静默退出：
- 运行
php -v 检查版本，Ubuntu 默认源的 php 可能太旧（如 8.1），建议用 sudo add-apt-repository ppa:ondrej/php && sudo apt update 切换到 Ondřej 的 PPA 源
- 运行
php --ri swoole，重点看两行：coroutine => enabled 和 Version => 5.1.1（示例），若显示 disabled 或版本
- 检查
opcache.enable_cli=0 是否在 php.ini 中显式设为 0 —— CLI 下开 opcache 是 Hyperf 协程调度崩掉的常见原因
pecl install swoole 后 extension 加载失败
很多用户执行
pecl install swoole 成功，但
php -m | grep swoole 无输出，本质是 extension 没被 PHP 加载：
- 先确认
swoole.so 文件路径：运行 find /usr -name "swoole.so" 2>/dev/null，常见位置是 /usr/lib/php/20220829/swoole.so（PHP 8.2）
- 在 php.ini 末尾加一行：
extension=/usr/lib/php/20220829/swoole.so（路径必须绝对且真实存在）
- 不要只写
extension=swoole —— 这依赖 extension_dir 配置，而该配置在不同发行版中指向不一致，硬编码路径最稳
- 改完后必须重启终端或运行
sudo systemctl restart php8.2-fpm（如果用了 fpm）或直接 php -v 验证
composer create-project 后启动报 “Class not found”
这通常不是框架问题，而是 autoloader 没刷新或权限卡住：
- 确保当前用户对项目目录有完整读写权：
sudo chown -R $USER:$USER myapp，尤其 runtime/ 目录需可写
- 删掉
vendor/ 和 composer.lock，重新跑 composer install --no-dev（加 --no-dev 避免 dev-only 包干扰）
- 别跳过
composer create-project 后的交互式提问：当问到 “Do you want to remove the existing VCS (.git) history?” 时，按 y；否则某些符号链接或缓存可能残留旧状态
- 首次启动前，手动执行一次
php bin/hyperf.php di:generate，强制生成依赖注入代理类，避免 runtime 下类加载失败
systemd 自启服务启动失败，journalctl 显示 “Permission denied”
systemctl start hyperf-app 报错但没具体信息？直接看日志最准：
- 运行
journalctl -u hyperf-app -n 50 -f，盯住最后一行错误，90% 是 WorkingDirectory 权限不对或 User= 指定的用户没权限读 bin/hyperf.php
-
User=www-data 是常见坑：Ubuntu 下 www-data 默认 shell 是 /usr/sbin/nologin，无法执行 PHP CLI，应改用有登录 shell 的普通用户（如 phpdev），并确保该用户属于 www-data 组
-
Environment=HOME=/var/www/my-hyperf 必须设置，否则某些扩展（如 opcache）初始化失败，导致进程秒退
- 别漏掉
sudo systemctl daemon-reload —— 修改 .service 文件后不 reload，systemd 根本不认新配置
真正卡住的地方，往往不在“怎么装”，而在 PHP CLI 环境和 systemd 用户上下文的细微错位。比如你在终端能
php bin/hyperf.php start，但 systemd 就起不来，八成是 HOME、PATH 或用户权限没对齐。动手前先跑通手动启动，再封装成服务，顺序不能反。
