Hyperf 3.1 在 PHP 8.2 下出现兼容性警告，本质是 hyperf/di、hyperf/validation 等组件未对齐 PHP 8.2 的 readonly 属性、联合类型推导及 Attributes 反射行为，须升级至明确支持的小版本（如 hyperf/di:^3.1.18、hyperf/validation:^3.1.15），并清除 runtime 缓存后验证 readonly 赋值报错、Validate 联合类型校验及 json_encode 性能提升是否生效。
Hyperf 3.1 在 PHP 8.2 下出现兼容性警告，基本不是“警告而已”，而是底层组件（如 hyperf/di、hyperf/validation、hyperf/http-message）未对齐 PHP 8.2 的联合类型推导、readonly 属性语义或 Attributes 反射行为导致的——不升级到明确标注支持 PHP 8.2 的小版本，启动时可能静默失败，或运行中触发 Fatal error: Cannot modify readonly property。
检查哪些包实际在报 PHP 8.2 兼容性警告
别只看 Composer install 输出，真实警告往往藏在启动日志或 php bin/hyperf.php start 的 stderr 中。常见来源有：
-
hyperf/div3.0.5 以下：无法正确反射public readonly string|int $id类型，抛ReflectionException: Property $id does not exist -
hyperf/validationv3.0.12 以下：对#[Validate]参数的联合类型（如string|null）校验失败，返回空数组而非错误 -
hyperf/http-messagev3.0.8 以下：解析psr/http-messagev2.x 时因 PHP 8.2 的array_is_list()行为变更，导致响应头丢失 -
hyperf/json-rpcv3.0.6 以下：在 PHP 8.2 + Swoole 5.1 环境下，参数反序列化时跳过readonly字段校验，造成数据污染
精准升级核心依赖，避开 composer update 全量覆盖
直接 composer update 容易拉入不兼容的 dev 分支或破坏 Hyperf 官方推荐组合。应逐个锁定已验证版本：
- 先确认当前 Hyperf 主版本：
composer show hyperf/framework，确保是v3.1.x（非v3.0.x或v3.2.x-dev） - 升级 DI 组件：
composer require hyperf/di:^3.1.18（v3.1.18 是首个完整支持 PHP 8.2readonly+ 联合类型的稳定版） - 升级 Validation：
composer require hyperf/validation:^3.1.15（修复了string|array|null多重联合类型解析崩溃） - 升级 HTTP 消息层：
composer require hyperf/http-message:^3.1.10（适配psr/http-messagev2.0 的 strict type 声明） - 执行
rm -rf runtime/container/ runtime/cache/清除旧注解与反射缓存，否则新版本不会生效
升级后必须验证的三个 PHP 8.2 特性是否真启用
版本号升了不等于特性就跑通。以下三处任一失败，说明升级没真正落地：
立即学习“PHP免费学习笔记（深入）”；
- 模型字段声明
public readonly int|string|null $status后，构造实例并赋值：$model->status = 'active';→ 必须报Fatal error；若能赋值成功，说明hyperf/di仍走旧反射逻辑 - 在控制器方法加
#[Validate(['id' => 'required|integer'])]，传{"id": null}→ 必须返回 422 错误；若返回 500 或静默通过，说明hyperf/validation未识别联合类型 - 启动后执行
php bin/hyperf.php server:monitor，观察json_encode耗时是否低于 0.05ms（PHP 8.1 环境通常 > 0.12ms）；若无变化，检查php --ri swoole是否含json => enabled
最容易被忽略的是：Hyperf 3.1 的 hyperf/di 升级后，所有自定义 #[Inject] 的服务类也必须显式声明构造函数参数类型，例如 public function __construct(private readonly UserService $userService)，否则 PHP 8.2 的属性提升（property promotion）会绕过 DI 容器注入，导致 $userService 为 null。
