hyperf 微服务零基础起步最常卡在三件事：swoole 未启用、服务注册未生效、rpc 接口调不通；需先确认 swoole 协程启用且版本≥5.1，再用 json-rpc 快速搭建双服务直连，最后排查网络、配置与 consul 健康检查。
Hyperf 微服务不是“装完就能跑”，零基础起步最常卡在三件事：swoole 没启用、服务注册没生效、RPC 接口调不通。直接上手跑通一个可通信的双服务（提供者 + 消费者）是关键分水岭，其余都是在此基础上叠加配置。
确认 swoole 扩展已加载且版本匹配
Hyperf 严重依赖 swoole 协程能力，但很多新手用的是 PHP-FPM 环境，或装了扩展却没启用。不检查这步，后续所有服务都启动失败或降级为同步阻塞模式。
- 运行
php --ri swoole，必须看到输出中包含support coroutine => enabled和version => 5.1+（Hyperf v3.x 要求 Swoole ≥ 5.1） - 若提示
Extension 'swoole' not present，需执行pecl install swoole，并在php.ini中添加extension=swoole.so - 注意：Docker 环境下必须用
hyperf/hyperf官方镜像（如hyperf/hyperf:8.2-alpine-swoole），自建镜像容易漏掉swoole编译参数
用 JSON-RPC 快速拉起第一个服务提供者
别一上来就配 Consul 或 Nacos——先让两个服务能本地直连通信，再引入注册中心。JSON-RPC 是 Hyperf 里最轻量、调试最直观的 RPC 方式。
- 安装必要组件：
composer require hyperf/json-rpc hyperf/rpc-server - 修改
config/autoload/server.php，追加一个 TCP server（端口避开 9501，默认 HTTP）：['name' => 'jsonrpc', 'type' => \Hyperf\Server\Server::SERVER_BASE, 'host' => '0.0.0.0', 'port' => 9504, 'sock_type' => SWOOLE_SOCK_TCP, 'callbacks' => [Event::ON_RECEIVE => [\Hyperf\JsonRpc\TcpServer::class, 'onReceive']], 'settings' => ['open_eof_split' => true]]
- 定义服务契约（interface）和实现类，放在
app/Contract/UserServiceInterface.php和app/Service/UserService.php，确保实现类加了#[AutoController]或手动在services.php中注册 - 启动后访问
telnet 127.0.0.1 9504能连上，说明 TCP Server 已就绪
消费者调用时连不上提供者？重点查这三点
常见现象是消费者抛出 Hyperf\Rpc\Exception\RpcClientException 或超时，根本原因往往不是代码写错，而是网络或配置层断开。
-
config/autoload/services.php中consumers配置必须含完整服务名、接口全限定类名、协议类型（jsonrpc）、以及nodes地址——本地开发时填['127.0.0.1:9504']，不要写localhost（Docker 容器内解析可能失败） - 消费者启动前，提供者必须已在运行；Hyperf 不支持自动重连，首次调用失败后不会自动恢复，需手动重启消费者进程
- 如果用 Docker，确保两个服务在同一个 network 下，且消费者容器能 ping 通提供者容器 IP（不是
localhost）；docker-compose.yml中避免只暴露9501，JSON-RPC 的9504也要映射或打通 internal network
Consul 注册成功但服务发现为空？别忽略健康检查路径
Consul UI 显示服务已注册，但消费者始终查不到实例，大概率是健康检查未通过，导致 Consul 将该实例标记为 critical 并剔除。
- Hyperf 默认注册时会带
check配置，但若你改过server.php或禁用了 HTTP server，/ping健康检查路径会 404 - 要么启用 HTTP server（哪怕只用来做健康检查），要么在
config/autoload/services.php的 provider 配置里显式指定check：'check' => ['http' => 'http://127.0.0.1:9501/ping', 'interval' => '10s', 'timeout' => '5s']
- Consul 日志里搜
failed to do check可快速定位是路径不可达还是超时
真正难的不是写代码，而是让服务间“看见彼此”——网络通路、协议对齐、健康状态这三层缺一不可。跑通第一个 JSON-RPC 调用后，再加注册中心、熔断、链路追踪，节奏才稳得住。
