php 8.2 是 hyperf 3.x 最稳定推荐版本，需同时安装 php8.2-cli 与 php8.2-dev，并启用 json、openssl、pdo、bcmath、sockets、xml、mbstring 等扩展，且必须设置 swoole.use_shortname = off 并验证协程真正启用。
Hyperf 3.x 必须用 PHP ≥ 8.1，PHP 8.2 是当前最稳选择
Hyperf 3.x 已彻底放弃对 PHP 7.4 和 8.0 的支持，php -v 输出低于 8.1.0 就别往下试了——不是报错就是静默失败。PHP 8.2 是目前 Hyperf 3.1–3.2 系列验证最充分的版本，协程稳定性、注解扫描准确率、连接池复用率都明显优于 8.1；而 PHP 8.3 虽已发布，但截至 2026 年 9 月，Swoole 5.1.x 尚未完全覆盖其新特性（如某些反射变更），不建议生产环境贸然升级。
装 PHP 8.2 时必须同时装 php8.2-cli 和 php8.2-dev
只装 php8.2-cli 会导致后续编译 Swoole 或 Redis 扩展失败，因为 phpize 和头文件都在 -dev 包里。Ubuntu/Debian 下缺一不可：
sudo apt install php8.2-cli php8.2-dev- 硬性依赖扩展也要一次性装齐：
php8.2-mbstring php8.2-xml php8.2-bcmath php8.2-sockets php8.2-pdo php8.2-opcache php8.2-json php8.2-openssl - 装完立刻验证：
php -m | grep -E 'mbstring|json|sockets'，漏一个就可能让hyperf/watcher启动失败或热重载卡住
swoole.use_shortname = Off 是启动前必关的开关
这个配置项不关，php bin/hyperf.php start 会直接报错：
ERROR Swoole short function names must be disabled before the server starts, please set swoole.use_shortname='Off' in your php.ini.
它和 opcache.enable_cli=1 一样，属于“看着能跑、其实协程已残废”的隐形杀手。操作要点：
- 找到真实生效的
php.ini：运行php --ini，看Loaded Configuration File路径 - 在该文件末尾加一行：
swoole.use_shortname = Off - 改完必须重启 CLI 环境（关掉终端重开，或
hash -r），否则php --ri swoole仍可能显示support coroutines: disabled
检查协程是否真启用，不能只信 php --ri swoole
php --ri swoole 显示 support coroutines: enabled 只代表扩展编译时打开了协程，不代表运行时已激活。Hyperf 要求运行时也开启，两个地方必须对齐：
-
config/autoload/server.php中'enable_coroutine' => true（Swoole v5+ 默认是true，但显式写死更保险） -
bin/hyperf.php文件最顶部（在<?php之后第一行）必须有：Swoole\Runtime::enableCoroutine(true); - 漏掉任一，
Hyperf\DbConnection查询就会阻塞主线程，HttpClient并发请求变成串行，现象是接口响应时间忽高忽低，查日志却没报错
php8.2-dev 和 bin/hyperf.php 顶部那行 enableCoroutine 调用——它们不报错，但会让整个协程链路形同虚设。php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
