Hyperf 运行必需 PHP 7.4+（推荐 8.0/8.1），核心扩展包括 json、mbstring、openssl、pdo 及数据库驱动、redis、sockets，CLI 模式还需 pcntl 和 posix；推荐启用 curl、zip、ctype、xml 及 Swoole（v4.8.13+/v5.0.0+），并禁用 CLI 下 OPcache。
Hyperf 运行需要一系列 PHP 扩展支持，缺一不可。核心依赖以 PHP 7.4+ 为基础，推荐使用 PHP 8.0 或 8.1 以获得最佳性能与兼容性。以下为必须安装的扩展清单及常见安装提示。
必需扩展（无一可少）
这些扩展是 Hyperf 启动和基础功能运行的前提：
-
json：处理 JSON 编解码，PHP 默认启用，确认未被禁用（
php -m | grep json） - mbstring：多字节字符串处理，路由、验证、国际化等模块强依赖
- openssl：HTTPS 请求、JWT 签名、gRPC TLS、Composer 安装均需此扩展
- pdo 及对应数据库驱动（如 pdo_mysql 或 pdo_pgsql）：DB 组件与 ORM 必须启用
- redis（或 phpredis）：缓存、锁、消息队列（如 Redis 驱动的 DelayQueue）依赖此扩展
- sockets：协程 TCP/UDP 客户端、WebSocket Server 底层通信所必需
-
pcntl 和 posix：仅在 CLI 模式下启动常驻进程（如
php bin/hyperf.php start）时需要，用于进程管理与信号处理
推荐启用的扩展（提升稳定性与能力）
虽非绝对强制，但不启用可能导致部分功能降级或报错：
-
curl：HTTP 客户端（
GuzzleHttp或Hyperf\HttpClient）底层依赖，建议开启 -
zip：执行
composer create-project或解压资源包时需要 - ctype 和 xml：部分组件（如 Swagger 文档生成、XML 解析）会间接调用
-
swoole（v4.8.13+ 或 v5.0.0+）：Hyperf 的底层协程引擎，必须通过
pecl install swoole安装并启用；注意关闭opcache.enable_cli=0（Swoole 5.0+ 要求 CLI 下禁用 OPcache）
检查与验证方法
快速确认环境是否就绪：
立即学习“PHP免费学习笔记（深入）”；
- 运行
php --ini查看配置文件路径，确保extension=swoole.so、extension=redis.so等已写入php.ini - 执行
php -m列出所有已加载扩展，逐项核对上文列表 - 进入项目目录，运行
php bin/hyperf.php start，若提示Extension xxx not loaded，即说明缺失 - 使用
php -r "echo Swoole\VERSION . \"\n\";"验证 Swoole 版本是否满足要求
常见问题提醒
避免踩坑的关键细节：
- Docker 用户请确认基础镜像含
swoole（官方推荐hyperf/hyperf:8.1-alpine或:8.1-slim） - Mac M1/M2 用户编译 Swoole 时需指定架构：
pecl install swoole --configureoptions 'enable-http2="no"'（避免 http2 依赖问题） - CentOS/RHEL 系统需先安装
epel-release和gcc等编译工具链再编译扩展 - Windows 下不支持 Swoole（Hyperf 官方不支持 Windows 生产环境），开发调试请使用 WSL2
