centos 7 安装 hyperf 运行环境需依次配置 epel/remi 仓库、安装 php 8.2 及 php-devel 等编译工具、启用 redis 和源码编译 swoole 扩展、配置 php.ini 并重启 php-fpm、安装 composer（推荐腾讯镜像）、最后用 create-project 初始化项目并启动。
在 CentOS 7 上顺利编译安装 Hyperf 运行环境，核心是满足其底层依赖：PHP（≥7.2）、Swoole（≥4.4）、Redis 扩展、以及可选的 OpenSSL、JSON、PDO 等。整个过程需按顺序处理系统源、PHP 版本、关键扩展、工具链和项目初始化，跳过任一环节都可能导致启动失败或功能异常。
配置可靠软件源并安装基础依赖
CentOS 7 自带 yum 源不含 PHP 7.2+ 和新版 Swoole，必须启用 EPEL 和 Remi 仓库：
- 安装 EPEL：sudo yum install -y epel-release
- 安装 Remi 仓库包（以 PHP 8.2 为例）：sudo yum install -y https://rpms.remirepo.net/enterprise/remi-release-7.rpm
- 启用 PHP 8.2 模块：sudo yum-config-manager --enable remi-php82
- 安装编译必需工具：sudo yum groupinstall -y "Development Tools"，再补全：sudo yum install -y php-devel php-pear openssl-devel gcc-c++ make autoconf
安装并验证 PHP 与核心扩展
确保 PHP 主体及关键扩展就位，且版本兼容：
- 安装 PHP 运行时及 CLI：sudo yum install -y php php-cli php-fpm php-common php-opcache php-json php-mbstring php-xml php-zip php-bcmath php-gd
- 检查版本：php -v 应输出 8.2.x；若仍为旧版，执行 sudo alternatives --config php 切换默认版本
- 安装 Redis 扩展：sudo yum install -y php-redis，确认 php -m | grep redis 有输出
- 安装 Swoole 扩展（推荐源码编译，避免 Remi 包版本滞后）：
下载对应 PHP 版本的 Swoole 源码（如 v5.1.2），解压后执行：
cd swoole-src && phpize && ./configure --enable-openssl --enable-http2 && sudo make && sudo make install
编译成功后，在 php.ini 中添加 extension=swoole.so，再重启 FPM：sudo systemctl restart php-fpm - 验证 Swoole 加载：php --ri swoole 应显示版本号与启用状态
安装 Composer 并创建 Hyperf 项目
Composer 是项目构建的关键工具，务必使用稳定镜像源：
- 下载安装：php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php && sudo mv composer.phar /usr/local/bin/composer - 切换国内镜像（腾讯云较稳定）：composer config -g repo.packagist composer https://mirrors.cloud.tencent.com/composer/
- 拉取骨架项目：composer create-project hyperf/hyperf-skeleton myapp
- 进入目录并启动：cd myapp && php bin/hyperf.php start
常见问题与快速排查
启动失败时，优先检查以下几项：
- Swoole 未启用或版本过低：运行 php --ri swoole，确认 version ≥ 4.4，且 enabled => true
- PHP 扩展缺失：Hyperf 默认需 redis、swoole、json、mbstring；用 php -m 全量检查
- 端口被占用：Hyperf 默认监听 9501，可用 sudo netstat -tuln | grep :9501 查看，修改 .env 中的 HTTP_PORT 即可
- 时区或 locale 异常：在 php.ini 中设置 date.timezone = Asia/Shanghai，并确保系统 locale 支持 UTF-8
