仅靠 composer require grpc/grpc 无法让 PHP gRPC 客户端工作——它只是 PHP 封装层，不提供网络能力；真正依赖已安装启用的 C 扩展 grpc，需通过 pecl 安装、配置 php.ini 并验证 extension_loaded('grpc')。
仅靠 composer require grpc/grpc 无法让 PHP gRPC 客户端工作——它不提供任何网络能力，必须先装好 C 扩展 grpc。
为什么 composer require grpc/grpc 后调用报 Class 'Grpc\Channel' not found？
这是最典型的误判起点。你看到 Packagist 上有 grpc/grpc 包，以为装完就能用，但实际它只是 PHP 封装层：类文件、客户端 stub、工具函数。真正发起 HTTP/2 连接、处理帧、管理 Channel 的，是底层的 C 扩展 grpc。
-
composer install只把 PHP 类复制进vendor/，不编译也不加载扩展 - 运行时找不到
Grpc\Channel，本质是extension=grpc.so没生效，或根本没安装 - 执行
php -m | grep grpc无输出，就说明扩展未加载——此时写再漂亮的 client.php 都会直接 fatal
如何确认并启用 PHP gRPC 扩展（Linux/macOS）
扩展必须独立安装，且要匹配当前 PHP 版本和 ABI。PECL 是标准路径，但容易卡在依赖上。
- 先确保系统级依赖到位：
autoconf、zlib-dev、php-dev、libprotobuf-dev（Ubuntu/Debian）或对应包 - 运行
pecl install grpc；若失败，尝试指定版本如pecl install grpc-1.64.0（查 PECL 页面 获取兼容列表） - 检查
php --ini输出的主配置路径，往对应php.ini里加一行：extension=grpc.so - 注意 CLI 和 Web SAPI（如 Apache/Nginx）可能用不同
php.ini，php -i | grep "Loaded Configuration File"确认你改的是对的那个 - 重启 PHP-FPM 或 Apache，再跑
php -r "var_dump(extension_loaded('grpc'));"，输出bool(true)才算过关
gRPC 客户端初始化时地址和凭据怎么填？
即使扩展装好了，new Grpc\Channel() 仍可能静默失败——错误不在代码语法，而在协议与服务端不匹配。
立即学习“PHP免费学习笔记（深入）”；
- 地址必须是
host:port格式，不能带http://或https://；gRPC 默认走 h2c（HTTP/2 明文），不是 HTTP/1.1 - 服务端监听
localhost:50051（明文），客户端用Grpc\ChannelCredentials::createInsecure() - 服务端启用了 TLS（如
443），客户端必须传ssl_target_name_override和Grpc\ChannelCredentials::createSsl()，否则 handshake 卡住、超时、无异常 - 域名解析慢或证书链不全时，
Channel构造可能直接失败但不抛异常——加个简单try/catch并检查$channel->getConnectivityState()能提前暴露问题
Protobuf 代码生成和 Composer 依赖怎么配才不冲突？
grpc/grpc 和 google/protobuf 都要装，但顺序和版本有讲究。
- 先装
composer require google/protobuf:^4.0（PHP 8+ 推荐 v4.x；v3.x 不兼容 PHP 8.2+ 的 typed property） - 再装
composer require grpc/grpc:^1.60（选与已装grpcC 扩展版本接近的，比如扩展是 1.64.0，PHP 包选 1.60–1.64 范围） -
protoc生成代码时，必须用匹配的grpc_php_plugin（不能混用旧版插件），否则生成的 client 类里会缺_simpleRequest方法 - 生成的 PHP 文件（如
Example/GreeterClient.php）需require_once正确路径，且命名空间要与.proto中package一致，否则new GreeterClient()找不到类
真正卡住人的从来不是写几行 client 代码，而是扩展没装对、地址格式写错、TLS 凭据漏传、或者 protobuf 版本和插件不配套——这些点不手动验证一遍，光看文档和示例代码永远跑不通。
