# 内部错误：gRPC-Web：来源 http://localhost:3000 的 CORS 预检失败

- **ID:** `grpc/grpc-web-cors-failure`
- **领域:** grpc
- **类别:** config_error
- **验证级别:** ai_generated
- **修复率:** 90%

## 根因

gRPC-Web 代理或服务器未对预检 OPTIONS 请求返回正确的 CORS 头。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| Envoy 1.26.0 | active | — | — |
| gRPC-Web 1.48.0 | active | — | — |

## 解决方案

1. ```
   Configure the gRPC-Web proxy (e.g., Envoy) to add CORS headers. Example Envoy config snippet: `cors: { allow_origin_string_match: [{ prefix: "http://localhost:3000" }], allow_methods: "POST, OPTIONS", allow_headers: "content-type,x-grpc-web", max_age: "86400" }`
   ```
2. ```
   If using a custom server, handle OPTIONS requests manually by returning 200 with appropriate CORS headers.
   ```

## 无效尝试

- **** — Browsers enforce CORS; it cannot be disabled client-side. (100% 失败率)
- **** — The preflight request (OPTIONS) must be handled explicitly, not just the POST. (60% 失败率)
- **** — This only works for non-browser environments; the error is specific to browser-based gRPC-Web. (50% 失败率)