在 centos 8 上稳定搭建 hyperf 的关键是避开环境、依赖、配置和系统级四大硬伤：必须用 php ≥ 8.1（通过 remi 仓库）、swoole ≥ 5.0.3、composer ≥ 2.5；初始化需补装 hyperf/http-server 并确认 server.php 监听 0.0.0.0:9501；控制器命名与注解路径须严格规范；还需关闭 selinux 或授权端口、放行 firewalld、调高 ulimit。
在 CentOS 8 上快速、稳定地搭建 Hyperf，关键不是“跳过步骤”，而是避开那些会让服务起不来、路由不生效、协程出错的硬伤点。CentOS 8 已停更（最后版本为 8.5.2111），系统基础组件（如 OpenSSL、libcurl）和 PHP 生态存在兼容性断层，直接照搬官方文档极易卡在环境或依赖环节。
一、环境准备：必须用对版本组合
Hyperf 3.x 要求严格，低版本会直接报错或静默失败：
-
PHP ≥ 8.1.0：CentOS 8 默认源只提供 PHP 7.2/7.4，必须启用
epel+remi-8.1或更高仓库（推荐 remi） -
Swoole ≥ 5.0.3：不能装旧版（如 4.8.x），否则启动时提示
Coroutine::create(): cannot be used in non-coroutine context -
Composer ≥ 2.5.0：低于此版本无法解析 Hyperf 3.2+ 的依赖约束，安装会卡在
hyperf/contract
执行命令一键就绪：
sudo dnf install -y epel-release sudo dnf install -y https://rpms.remirepo.net/enterprise/remi-release-8.rpm sudo dnf module reset php sudo dnf module enable php:remi-8.1 sudo dnf install -y php php-cli php-devel php-pdo php-mbstring php-xml php-json php-opcache sudo pecl install swoole echo "extension=swoole.so" | sudo tee /etc/php.d/40-swoole.ini curl -sS https://getcomposer.org/installer | php sudo mv composer.phar /usr/local/bin/composer
二、项目初始化：跳过骨架陷阱
官方骨架默认不含 HTTP 服务组件，php bin/hyperf.php start 后监听端口为空、curl 直接超时——这是新手最高频的“服务没起来”错觉：
- 用
hyperf-skeleton创建后，必须立即执行：composer require hyperf/http-server - 不要用
hyperf/http-server的 dev 分支或 alpha 版，锁定^3.2稳定版 - 确认
config/autoload/server.php中'port' => 9501未被注释，且'host'是'0.0.0.0'（非'127.0.0.1'，否则宿主机访问不到）
三、控制器与路由：避免 404 黑盒
写完控制器却访问返回 404？大概率是注解或路径细节出错：
-
#[AutoController(prefix: '/api')]中的prefix必须以/开头、不以/结尾（'/api/'会导致路由匹配失败） - 控制器类名必须含
Controller后缀，且文件名与类名严格一致（IndexController.php→class IndexController） - 首次启动前，务必运行
php bin/hyperf.php route:list，确认输出中出现GET | /api/index行，否则注解未扫描
四、CentOS 8 特有避坑项
系统级限制容易被忽略，但会直接导致协程异常或连接失败：
-
SELinux 默认启用：可能拦截 Swoole 绑定端口，临时关闭验证：
sudo setenforce 0；生产环境请用semanage port -a -t http_port_t -p tcp 9501 -
防火墙放行端口：CentOS 8 默认用
firewalld，运行sudo firewall-cmd --add-port=9501/tcp --permanent && sudo firewall-cmd --reload -
ulimit 文件描述符不足：Hyperf 高并发依赖大量 socket，启动前执行
ulimit -n 65535，并写入/etc/security/limits.conf
