不能直接用 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 代码不执行，Swoole onStart 回调没触发，进程僵在那儿
• 根本原因：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

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 → 转成 gRPC UserService/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 帧内容才能确认。