hyperf项目初始化须检查php≥8.1和swoole≥5.0，确认协程启用；nacos服务注册配置不可依赖.env，需硬编码或提前注入；json-rpc调用需双侧设超时；连接池参数须匹配swoole协程数避免雪崩。
Hyperf 项目初始化必须检查 Swoole 和 PHP 版本
Hyperf 不是普通 PHP 框架，它强依赖 Swoole 协程运行时。PHP 8.1+ 和 Swoole 5.0+ 是当前生产环境最低安全线——低于此版本会遇到协程上下文丢失、Co::sleep 行为异常、连接池复用失败等隐蔽问题。
- 执行
php --ri swoole确认输出中包含coroutine => enabled和version => 5.x - 若用 Docker，镜像不能选
php:8.1-cli这类基础镜像，必须显式安装 Swoole：pecl install swoole并启用extension=swoole.so -
composer create-project hyperf/hyperf-skeleton后立即运行php bin/hyperf.php start，观察控制台是否打印Server started on http://0.0.0.0:9501而非报Swoole\Coroutine not found
服务注册到 Nacos 的关键配置项不能写在 .env 里直接引用
Nacos 客户端初始化发生在 DI 容器构建早期，而 .env 中的值若未被 config/autoload/constants.php 显式加载，services.php 里用 env('NACOS_ADDRESS') 会返回 null，导致服务根本无法注册——现象是 Nacos 控制台看不到实例，但 Hyperf 日志无报错。
- 正确做法：在
config/autoload/services.php中硬编码或通过BaseConfigProvider提前注入，例如：'address' => 'nacos-server:8848' - 必须启用健康检查，否则 Nacos 会把瞬时启动失败的服务也标记为 healthy：
'metadata' => ['preserved.heart.beat.timeout' => 15] - 服务名（
name）必须全小写且不含下划线，Nacos 对大小写敏感，OrderService和orderservice被视为两个服务
JSON-RPC 调用失败时优先查 Consumer 配置而非网络
Hyperf 的 Consumer 是静态绑定的，一旦配置错误，调用会静默 fallback 到本地空实现或抛出 ClassNotFoundException，而不是你预期的连接超时错误。
- 检查
config/autoload/services.php的consumers数组是否包含目标服务的完整类名，例如：'App\Service\OrderServiceInterface' - 接口类必须带
interface声明，且不能有方法体；实现类需加#[RpcService]注解并指定name与 consumer 一致 - 超时必须双侧设置：服务端
@RpcService(timeout=3000)+ 客户端@RpcClient(timeout=3000)，只设一边无效
协程环境下 Redis/MySQL 连接池参数不匹配会导致请求卡死
Hyperf 默认的连接池大小（如 Redis max_connections = 20）在压测时极易成为瓶颈。但盲目调大又可能触发 Swoole 的 fd 限制或 MySQL 的 max_connections 拒绝连接。
- 先确认 Swoole 全局最大协程数：
swoole_get_option(SWOOLE_OPTION_MAX_CORO_NUM)，连接池max_connections总和不应超过此值的 70% - MySQL 连接池的
min_connections建议设为1，避免冷启动时首次查询等待建连 - Redis 连接池必须关闭
use_pipeline（默认 false），开启后在高并发下易出现响应错乱
真实线上问题往往卡在连接池和 Nacos 实例心跳的耦合上：一个服务实例因连接池耗尽无法上报心跳，Nacos 就把它踢掉，流量又压向剩余实例，形成雪崩。这点容易被忽略。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
