Hyperf 当前（2026年8月）官方稳定支持 PHP 8.1–8.3，不支持未发布的 PHP 8.5 及尚处 alpha 阶段的 8.4；强行使用会导致 composer install 失败、注解扫描异常、协程静默失效。
单机升级 PHP 版本以保障 Hyperf 正常部署运行，核心不是“升得越高越好”，而是升到 Hyperf 明确支持且稳定验证过的版本区间。当前（2026 年 8 月）Hyperf 官方稳定支持的 PHP 版本是 8.1、8.2、8.3，不支持 PHP 8.4 alpha/beta，更不存在 PHP 8.5（尚未发布）。盲目升级到未适配版本，会导致 composer install 直接失败、注解扫描异常、协程静默失效等底层问题。
确认当前环境真实版本
别只看 php -v 输出里带的 dev、snapshot 或构建时间——这些可能只是本地编译分支。执行以下命令获取纯净、可验证的版本号：
-
php -r "echo PHP_VERSION;"—— 输出如8.2.22才是真实主版本 -
php --ini—— 查看实际加载的php.ini路径，避免被phpbrew、brew或 Docker 内多配置干扰 -
php --ri swoole | grep "support coroutines"—— 必须显示enabled，否则协程链路从根上就断了
选择并安装推荐版本（PHP 8.2 最稳）
PHP 8.2 是 Hyperf 3.x 系列经过最多生产验证的版本，协程稳定性、扩展兼容性、错误提示友好度均最优：
- Linux（Debian/Ubuntu）：
apt install php8.2-cli php8.2-dev php8.2-bcmath php8.2-mbstring php8.2-xml php8.2-sqlite3 php8.2-pdo php8.2-mysql php8.2-opcache php8.2-json php8.2-openssl php8.2-sockets - macOS（M1/M2/M3）：
brew install php@8.2 swoole—— Homebrew 已自动适配 ARM 架构，比手动pecl install可靠得多 - 宝塔面板：安装 PHP 8.2.32（非 8.1 或 8.3），安装时务必勾选
pcntl和sockets扩展，否则hyperf.php start启动后无监听
关键配置必须同步更新
仅装对 PHP 版本还不够，以下三项配置任一缺失，Hyperf 就无法启用协程能力：
立即学习“PHP免费学习笔记（深入）”；
- 在
php.ini中显式关闭 Swoole 短名：swoole.use_shortname = Off - 检查
config/autoload/server.php中'enable_coroutine' => true已设置（Swoole v5+ 默认为 true，但写死更稳妥） - 确保
bin/hyperf.php文件最顶部（第一行可执行代码前）有：Swoole\Runtime::enableCoroutine(true);
升级后必做验证动作
不要只看 php bin/hyperf.php start 是否输出 “listening”，要验证实际能力：
- 执行
php bin/hyperf.php route:list—— 若无任何路由输出，说明注解未扫描，大概率是config/autoload/annotations.php中scan路径未包含app/Controller - 用
curl -v http://127.0.0.1:9501/api/index测试基础接口，观察响应头中是否有X-Powered-By: Hyperf - 在控制器中调用
Hyperf\DbConnection\Db::table('users')->first()，若超时或报 PDO 错误，说明数据库组件未走协程驱动，需检查是否用了Hyperf\DbConnection而非原生 PDO
