浏览器调用接口时，Network面板显示HTTP 200，页面却提示RPC失败；或者OPTIONS预检通过，真正POST又被拦截。这类问题要先确认使用的是gRPC-Web还是原生gRPC，因为两者在浏览器、代理和服务端之间的封装不同。
gRPC-Web解决什么限制
原生gRPC依赖HTTP/2、二进制帧与Trailer等能力，浏览器JavaScript不能像普通原生客户端那样完全控制底层HTTP/2连接。gRPC-Web使用适合浏览器的传输格式，再由支持该协议的代理转换到后端gRPC服务。
两段连接可能不是同一协议
| 链路 | 常见形式 | 排查重点 |
|---|---|---|
| 浏览器到代理 | gRPC-Web，可能经HTTP/1.1或HTTP/2 | CORS、Content-Type、响应暴露头 |
| 代理到后端 | 原生gRPC over HTTP/2 | 协议升级、TLS、服务名、Deadline |
| 代理转换层 | gRPC-Web Filter或网关插件 | 格式转换、Trailer、流式支持 |
浏览器到代理使用HTTP/1.1并不说明后端也能降级到HTTP/1.1。原生gRPC后端通常仍要求正确的HTTP/2连接。
Content-Type为什么重要
gRPC-Web常见二进制或文本编码形式，对应的Content-Type不同。代理、WAF或应用框架若把请求当普通JSON解析、压缩或改写，可能破坏帧。记录实际请求和响应头，与客户端库预期比较，不要只检查URL是否正确。
CORS预检通过仍可能失败
浏览器跨域请求会校验Origin、方法、请求头和响应暴露头。预检允许POST并不代表服务响应中的状态信息可被JavaScript读取。应按客户端实际使用的头配置允许与暴露列表；携带Cookie或认证信息时，还要设置精确来源并评估CSRF边界。
HTTP 200不代表RPC成功
gRPC业务状态可能通过grpc-status和grpc-message表达。gRPC-Web会把Trailer编码到响应末尾或按实现暴露。只监控HTTP状态会漏掉认证失败、方法不存在、Deadline超时等RPC错误，日志与指标应同时记录两类状态。
流式调用有哪些限制
不同gRPC-Web客户端和代理对服务端流、客户端流和双向流支持并不一致。反向代理缓冲、压缩或读取超时还会让服务端流看似一次性返回。先核对所用库与代理版本支持，再关闭不适合流式响应的缓冲并设置心跳或合理Deadline。
路径重写容易错在哪里
gRPC方法路径包含服务与方法名称，代理若像普通网站那样删除前缀或重写大小写，后端可能返回UNIMPLEMENTED。多个后端共享网关时，应按明确服务路由，不要用过宽正则把所有RPC转到默认集群。
TLS终止与后端h2
代理可以在前端终止TLS，再与后端建立新的TLS或明文HTTP/2连接。两段证书、SNI、ALPN和信任策略要分别检查。前端网页证书正常，不能证明代理到后端的证书与HTTP/2协商正常。
与原生gRPC问题如何区分
先用受支持的原生客户端从代理所在网络调用后端，验证服务名、TLS与RPC本身；再测试浏览器到转换代理。关于Deadline、Keepalive和HTTP代理边界，可继续查看原生gRPC经过HTTP代理的排查方法。
最短排查路径
- 确认客户端库实际发送gRPC-Web二进制还是文本格式；
- 检查OPTIONS与POST的Origin、允许头和暴露头；
- 确认代理启用gRPC-Web转换并使用HTTP/2连接后端；
- 同时记录HTTP状态、grpc-status和grpc-message；
- 关闭会破坏流式传输的缓冲或错误压缩；
- 核对路径重写、超时、最大消息和后端日志。
结论
gRPC-Web故障通常位于浏览器约束、协议转换或后端gRPC三者的接缝。把两段连接分别验证，并保留CORS、Content-Type、Trailer和RPC状态证据，比反复调整一个反向代理超时更有效。
