不能直接用 Grpc\Server：因其为阻塞单进程模型，与 Swoole 协程/事件循环互斥，启动后独占进程、卡死事件循环，导致 Swoole 功能失效。
PHP 项目里直接用 Grpc\Server 启动 gRPC 服务，在 Swoole 环境下会失败——因为原生 gRPC PHP 扩展的 Server 是阻塞式、单进程模型，和 Swoole 的协程/事件循环不兼容。 正确做法是让 Swoole 充当 HTTP/2 网关或协程客户端，把 gRPC 请求代理出去，或用 Swoole 原生实现服务端逻辑（需绕过官方 Grpc\Server）。
为什么不能直接 new Grpc\Server()？
官方 Grpc\Server 启动后会独占进程、阻塞运行，无法接入 Swoole 的 Swoole\Http\Server 或 Swoole\Coroutine\Server。它不识别协程上下文，也不支持连接复用和请求生命周期管理。一旦启动，Swoole 的事件循环就卡死，go、defer、Channel 全部失效。
- 现象：调用
$server->start()后，后续 PHP 代码不执行，SwooleonStart回调没触发，进程僵在那儿 - 根本原因：gRPC PHP 扩展的
Server是基于 C 层 epoll + pthread 的老式模型，和 Swoole 协程调度器互斥 - 验证方式：
ps aux | grep php只能看到一个主进程，无 worker 进程，strace -p显示在accept()上休眠
用 Swoole\Http\Server 搭建 gRPC 网关（推荐过渡方案）
这是最稳妥、兼容性最强的集成方式，尤其适合已有 HTTP/1.1 接口需对接新 gRPC 后端的场景。核心是让 Swoole 解析 HTTP/1.1 JSON 请求，按 .proto 规则转换为 Protobuf，再用 Grpc\Channel 转发到真实 gRPC 服务。
Swoole 6.1.1 是一个专为 PHP 设计的高性能事件驱动并发网络引擎。作为稳定版，它修复了编译时对 zlib 依赖的缺失及 curl 模块的内存安全风险。该版本支持协程、多线程与多进程架构，内置 TCP/HTTP/WebSocket 服务器，能够显著提升 PHP 在微服务、实时通信等场景下的执行效率与并发能力。
- 必须启用 Swoole 的 HTTP/2 支持：
./configure --enable-http2编译时加参数，否则无法处理 gRPC 的 HTTP/2 帧 -
ProtobufConverter类要严格按.proto中的package和字段编号做映射，比如user.UserRequest对应id = 1，错一位就会解包失败 - 客户端调用路径必须匹配 gRPC 方法名：HTTP POST
/user.UserService/GetUser→ 转成 gRPCUserService/GetUser，大小写和斜杠不能错 - 连接池要用
Swoole\Coroutine\Channel管理Grpc\Channel实例，避免每次请求都新建 channel（开销大且易触发 fd 耗尽）
用 Swoole\Coroutine\Server 实现纯协程 gRPC 服务端
跳过官方 Grpc\Server，自己解析 HTTP/2 帧并反序列化 Protobuf。这要求你手动处理 gRPC 的帧格式（length-prefixed messages）、metadata、status code 封装等。适合对性能压榨极致、且团队熟悉 HTTP/2 二进制流的项目。
- 底层依赖
ext-http2（Swoole >= 4.8.0 内置），不能用Swoole\Server，必须用Swoole\Coroutine\Server - 接收数据后先读取前 5 字节：第 1 字节是压缩标志（0x00 或 0x01），后 4 字节是 message length（网络字节序），少读或多读都会导致后续解码崩溃
- Protobuf 反序列化必须用生成类的
parseFrom方法，不能用json_decode或unserialize，否则字段丢失 - 响应必须写入完整的 gRPC HTTP/2 frame：status header（
:status: 200）、content-type（application/grpc+proto）、grpc-status（0表示 OK）
常见报错与定位点
遇到问题优先查这三处，80% 的集成失败都集中在这里：
-
GRPC_STATUS_UNIMPLEMENTED：HTTP 路径没映射对，比如客户端发/helloworld.Greeter/SayHello，但网关只配置了/SayHello -
Protocol error: invalid frame size：Protobuf 编码长度头错误，大概率是pack('N', $len)用了主机字节序而非网络字节序（应改用pack('N', htonl($len))） -
Connection refused但telnet host 50051通：Swoole 客户端没设对 credentials，Channel::CREDENTIALS_NONE用于本地测试，生产环境必须配 TLS 或自定义ChannelCredentials::createInsecure()
真正难的不是写通第一版，而是 .proto 文件变更后，PHP 生成类、网关映射规则、客户端调用链三者同步更新——漏掉任意一环，错误就藏在看似正常的日志里，得靠抓包看 HTTP/2 DATA 帧内容才能确认。
