Nginx 配置 gRPC 代理时必须拦截 OPTIONS 预检请求并返回 204，避免转发至不支持该方法的 gRPC 后端；需在 grpc_pass 前用 if ($request_method = 'OPTIONS') { return 204; } 拦截，正确设置 CORS 头、禁用缓冲，并隔离 HTTP/1.1 预检与 HTTP/2 gRPC 流量。
在 Nginx 同时配置 gRPC 代理和跨域请求的场景下，OPTIONS 预检请求不能被当作普通 HTTP 请求透传给 gRPC 后端——gRPC 服务通常不处理 OPTIONS，直接转发会导致 404、502 或连接中断。正确做法是：**由 Nginx 在网关层拦截并响应 OPTIONS，同时确保它不干扰 gRPC 流量的 HTTP/2 升级路径**。
明确区分请求类型，避免 OPTIONS 进入 grpc_pass
gRPC 使用 HTTP/2 和二进制帧，不兼容 OPTIONS 预检语义。若 location 块中直接用 grpc_pass 且未前置拦截，Nginx 会把 OPTIONS 当作 gRPC 流量尝试转发，引发协议错误（如 426 Upgrade Required 或 “invalid frame”）。必须通过匹配方法提前终止流程：
- 使用
if ($request_method = 'OPTIONS') { ... return 204; }拦截，且该块必须写在grpc_pass之前 - 不要在
grpc_pass所在的 location 内依赖后端返回 CORS 头——gRPC 服务一般不设 Access-Control-* 头 - 若使用 upstream 负载均衡，确保 OPTIONS 不参与轮询分发，否则不同节点响应不一致会触发浏览器跨域拒绝
预检响应需适配 gRPC 代理环境的协议约束
Nginx 处理 OPTIONS 时，要兼顾它所处的上下文：该 server 已启用 HTTP/2（因 gRPC 要求），但 OPTIONS 本身仍是 HTTP/1.1 兼容请求。配置需避免协议冲突：
- 显式设置
add_header Access-Control-Allow-Origin "$http_origin" always;（动态匹配前端 origin，比硬写*更安全） - 透传客户端声明的请求头：
add_header Access-Control-Allow-Headers "$http_access_control_request_headers" always; - 返回前加
add_header Content-Length 0;和add_header Content-Type text/plain;，防止某些客户端对空响应体解析异常 - 禁用缓冲：
proxy_buffering off;（放在 if 块内或通过 map 控制），避免小响应被卡住
确保 gRPC 主流量不受预检配置干扰
同一 location 下混用 OPTIONS 拦截与 grpc_pass 时，容易因指令顺序或隐式继承导致 gRPC 连接异常。关键隔离点：
-
grpc_pass只应出现在非 OPTIONS 请求路径中；不要在 if 块里写grpc_pass，也不要用try_files等间接跳转引入歧义 - 关闭所有与 gRPC 无关的 proxy 指令：如
proxy_set_header Upgrade $http_upgrade;对 gRPC 无效，反而可能污染头部 - 超时设置分开管理：gRPC 用
grpc_read_timeout/grpc_send_timeout；OPTIONS 无需长超时，保持默认即可 - 若需统一管理 CORS，建议将 OPTIONS 处理提取到独立 location，例如
location = /healthz { ... }或按路径前缀拆分（如location ^~ /api/处理 REST+OPTIONS，location /grpc/专用于grpc_pass）
验证是否生效的实操要点
调试阶段可快速确认配置是否到位：
- 用 curl 发送预检：
curl -X OPTIONS -H "Origin: https://example.com" -H "Access-Control-Request-Method: POST" -I http://your-domain/api/xxx，检查返回是否为 204 且含完整 CORS 头 - 抓包观察：OPTIONS 响应不应出现
HTTP/2版本标识（它是 HTTP/1.1 语义），而真实 gRPC 请求应显示h2协议协商成功 - 查看 error log：若出现
upstream prematurely closed connection或client sent invalid request，大概率是 OPTIONS 被误送入 gRPC 流程 - 注意 Nginx 版本限制：if + add_header 在 1.7.0+ 才可靠支持；旧版本请改用 map + add_header 全局方式
