PHP 8.2 是 Hyperf 单机部署黄金版本，需搭配 Swoole 5.1+、禁用 opcache.enable_cli、启用协程并验证；8.1 仅语法兼容不推荐生产，8.3 需绕开 json_throw_on_error 和枚举键坑，8.4 及以上暂不支持。
Hyperf 在单机服务器上部署，核心不是“能跑起来”，而是“协程真正生效、组件链路完整、请求稳定不卡死”。PHP 版本不是孤立参数，它和 Swoole、扩展、配置强绑定。当前（2026年8月）生产环境最稳妥的选择是 PHP 8.2 + Swoole 5.1+，而非盲目追新或沿用旧版。
PHP 8.1 是最低门槛，但不推荐用于生产
Hyperf 3.x 明确要求 PHP ≥ 8.1，但 8.1 仅满足语法兼容，实际运行中易暴露边缘问题：
- 枚举（
enum）、只读类（readonly class）等特性在 8.1 中尚不成熟，Hyperf 的 DI 容器反射逻辑偶发异常 -
opcache.enable_cli=0若未显式关闭，会导致注解扫描缓存失效，改了#[GetMapping]却不生效 - Ubuntu/Debian 系统自带的
php8.1包常缺php8.1-dev，导致pecl install swoole编译失败，只能装非协程版
✅ 验证命令：
php -r "echo PHP_VERSION_ID >= 80200 ? 'ok' : 'too old';"
输出ok才算真正达标（即 ≥ 8.2）
PHP 8.2 是单机部署黄金组合
该版本与 Hyperf 3.1.x 深度对齐，协程稳定性、错误提示、连接池复用率均达到最佳平衡：
- 必装扩展：
php8.2-cli、php8.2-dev、php8.2-json、php8.2-openssl、php8.2-pdo、php8.2-bcmath、php8.2-sockets、php8.2-xml、php8.2-mbstring - Swoole 必须用
pecl install swoole安装，过程中明确选y启用协程支持 - php.ini 中必须写死：
swoole.use_shortname = Off opcache.enable_cli = 0
- 启动前强制验证协程可用性：
php -r "Swoole\Runtime::enableCoroutine(true); co::sleep(0.001); echo 'coroutine ok';"
PHP 8.3 可用，但需绕开两个坑
Hyperf 3.1.x 已适配 PHP 8.3，但以下配置若遗漏，服务会静默降级为同步模式：
立即学习“PHP免费学习笔记（深入）”；
-
json_throw_on_error默认开启 → 所有json_decode()调用必须加JSON_THROW_ON_ERROR标志，否则返回null不报错 -
config/autoload/dependencies.php中禁止使用枚举作为数组键（如MyEnum::Case => Service::class），该文件可能被低版本 CLI 加载器预解析
⚠️ 别信
php -v显示8.3.0-dev就以为是稳定版——运行php -r "echo PHP_RELEASE_VERSION;"看真实小版本号，开发机编译的 alpha 分支不可用于生产。
PHP 8.4 及更高版本目前不支持
截至 2026 年 8 月，PHP 8.4 仍处于 RC 阶段，Hyperf 官方 composer.json 中的约束仍是 "php": "^8.1 || ^8.2 || ^8.3"。尝试安装会直接触发 Composer 冲突：
Your requirements could not be resolved to an installable set of packages.
所谓“PHP 8.5”纯属误传——PHP 官方从未发布 8.5，最新稳定版为 8.3.10，8.4 预计 2026 年底发布。
不复杂但容易忽略
