Hyperf 3.0 原生支持 PHP 8.2，但需手动配置：启用 swoole/json 扩展（php --ri swoole 显示 json => enabled）、模型属性声明为 public readonly int|string|null $field 并同步更新 $casts、连接池设 'reset' => false 与 'lazy' => true、注解扫描器忽略 readonly 或升级 hyperf/di 至 v3.0.6+。
Hyperf 3.0 原生支持 PHP 8.2，但 hyperf/database 组件默认不启用 PHP 8.2 的协程 JSON 编解码、只读属性（readonly）、联合类型推导等特性——必须手动对齐配置与代码写法，否则协程上下文丢失、模型属性赋值失败或 JSON 响应性能无提升。
确认 Swoole JSON 扩展已启用且生效
PHP 8.2 下的 JSON 性能跃升依赖 swoole/json 扩展，而非原生 ext-json。Hyperf 3.0 只有在该扩展加载后才自动切换至协程版 json_encode/json_decode。
- 执行
php --ri swoole，输出中必须含json => enabled；若为disabled或缺失，说明未编译进 Swoole 或被禁用 - 检查
php.ini中是否误加了disable_functions = json_encode,json_decode—— 这会强制回退到阻塞版，且无任何报错提示 - 验证方式：启动服务后调用一次接口，再执行
php bin/hyperf.php server:monitor，观察json_encode耗时是否显著低于同负载下 PHP 8.1 环境
Database 模型需显式声明 readonly 属性并适配联合类型
PHP 8.2 引入 readonly 类属性 + 更严格的联合类型校验，而 hyperf/database 的 Eloquent 模型若仍沿用 PHP 7.x 风格写法（如 public $id），会在构造时触发 Fatal error: Cannot modify readonly property。
- 所有模型字段必须改为
public readonly int|string|null $id形式（注意：不能是public readonly ?int $id，PHP 8.2 不允许?与readonly共存） - 若字段可能为
null，写成public readonly int|string|null $status，并在$casts中明确映射：protected array $casts = ['status' => 'integer'] -
hyperf/databasev3.0.5+ 已兼容此写法，但旧版（如 v3.0.0）需先升级组件：composer update hyperf/database
连接池配置必须关闭 reset 并启用 lazy
PHP 8.2 的 GC 行为变化导致 Swoole 连接池在 reset 模式下频繁触发析构，引发 MySQL 连接重置失败或 mysqli::query(): MySQL server has gone away 错误。
立即学习“PHP免费学习笔记（深入）”；
- 修改
config/autoload/databases.php中对应数据库的pool配置：'reset' => false, 'lazy' => true - 确保
max_idle_time≥ 60（单位秒），避免空闲连接被 MySQL 主动断开后，Hyperf 未及时感知而复用失效连接 - 若使用
hyperf/db-connectionv3.0.4+，可额外开启'auto_reconnect' => true，但仅作为兜底，不能替代连接池健康检测
注解扫描器需跳过 readonly 属性解析
Hyperf 3.0 默认注解扫描器（Hyperf\Di\Annotation\Scanner）在 PHP 8.2 下会尝试反射 readonly 属性的 setter，触发 ReflectionException: Cannot set readonly property，导致 bin/hyperf.php start 启动卡死或路由注册失败。
- 临时绕过：在
config/autoload/annotations.php中添加'scan' => ['ignore_annotations' => ['readonly']] - 根治方案：升级
hyperf/di至 v3.0.6+，该版本已修复对readonly属性的反射安全处理 - 验证方式：启动后访问任意
@GetMapping接口，若返回 404 或日志中出现ReflectionException，说明扫描器仍在尝试解析readonly
最易被忽略的是 readonly 属性与 $casts 的协同——只改属性声明却不更新 $casts，会导致数据库写入时类型强转失败，错误静默吞没；而只改 $casts 却不加 readonly，又无法享受 PHP 8.2 的内存优化。这两者必须同步调整。
