前端 CORS 预检失败排查流程：从请求头到网关响应

前端联调接口时，跨域问题经常看起来很玄：业务接口明明存在，Postman 能调通，浏览器却报 CORS 错误；有时 GET 可以，POST 不行；有时本地环境正常，一上测试环境就失败。

这篇文章不只解释概念，而是整理一套完整排查流程：先判断是否触发预检，再看浏览器请求头、OPTIONS 响应、网关转发和携带 Cookie 的配置。按这个顺序查，通常能很快定位是前端请求写法、后端响应头还是中间代理的问题。

目标和边界：先区分简单请求和预检请求

CORS 的核心不是“前端能不能访问某个域名”，而是浏览器是否允许当前页面读取跨域响应。服务端可能已经返回了内容，但只要响应头不符合浏览器规则，前端代码仍然拿不到结果。

排查前先分清两类请求：

• 简单请求：浏览器直接发业务请求，只检查响应里的跨域头。
• 预检请求：浏览器先发 OPTIONS，确认方法、请求头和来源被允许后，才会继续发真实请求。

很多联调卡点都在预检阶段：真实接口还没被调用，浏览器已经因为 OPTIONS 没通过而拦下了。

全流程总览：浏览器到接口的跨域链路

一个完整的 CORS 请求链路可以拆成五步：浏览器判断、发送预检、服务端返回允许信息、浏览器放行业务请求、前端读取响应。

阶段一：确认是否触发 OPTIONS 预检

先打开浏览器开发者工具的 Network 面板，过滤接口路径，观察业务请求前面有没有一条 OPTIONS。如果有，说明问题可能发生在预检阶段。

常见触发原因有：

• 使用 PUT、DELETE、PATCH 等方法。
• 请求里带了自定义头，比如 Authorization、X-Trace-Id。
• 提交的 Content-Type 是 application/json。

fetch("https://api.example.test/orders", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer token"
  },
  body: JSON.stringify({ page: 1 })
});

这段请求很常见，但它会触发预检。此时排查重点不在 POST 接口本身，而在服务器是否正确处理了 OPTIONS。

阶段二：检查服务端 CORS 响应头

预检响应至少要回答三个问题：允许哪个来源、允许哪些方法、允许哪些请求头。示例响应头如下：

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://admin.example.test
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization, X-Trace-Id
Access-Control-Max-Age: 600

如果前端请求带了 Authorization，但服务端没有把它放进 Access-Control-Allow-Headers，浏览器会认为预检失败。真实接口不会继续发送。

这里的检查点很明确：预检响应状态码要正常，允许来源要匹配当前页面，允许方法和允许请求头要覆盖真实请求。

阶段三：排查网关和反向代理转发

很多项目里，前端访问的不是后端服务本身，而是 Nginx、API 网关或云负载均衡。服务端代码写对了，网关没有透传 OPTIONS，也会失败。

典型表现是：

• 后端本机调 OPTIONS 正常，浏览器访问域名失败。
• OPTIONS 被网关返回 404、405 或 502。
• 业务响应里有跨域头，预检响应里没有。

这一步建议把请求链路拆开看：浏览器到网关、网关到服务、服务返回网关、网关返回浏览器。只要其中一段丢了跨域响应头，浏览器就会拦截。

阶段四：处理 Cookie 和凭证场景

如果接口需要携带 Cookie，配置会更严格。前端要显式打开凭证，服务端也不能简单返回通配来源。

fetch("https://api.example.test/profile", {
  credentials: "include"
});

Access-Control-Allow-Origin: https://admin.example.test
Access-Control-Allow-Credentials: true

注意：携带凭证时，Access-Control-Allow-Origin 不能使用 *。它必须是明确来源，并且要和当前页面来源匹配。

我的推荐流程

1. 先在 Network 面板确认有没有 OPTIONS。
2. 如果有，先看 OPTIONS 状态码，再看响应头是否完整。
3. 核对真实请求的 method、headers、Content-Type 是否都被允许。
4. 如果本机服务正常，继续排查网关是否透传 OPTIONS 和响应头。
5. 如果请求带 Cookie，确认前端凭证配置和服务端来源配置都正确。
6. 最后再看业务接口本身，避免一上来就怀疑后端业务代码。

常见误区

误区一：Postman 能通就说明接口没问题

Postman 不受浏览器同源策略限制。它能调通，只能说明接口可达，不能说明浏览器允许前端读取跨域响应。

误区二：只给业务接口加跨域头

如果请求触发预检，OPTIONS 响应也必须有跨域头。只给 POST 或 GET 加头，预检仍然可能失败。

误区三：携带 Cookie 时使用通配来源

带凭证请求必须返回明确来源，不能用 * 兜底。否则浏览器会直接拒绝。

速查表

总结一下，CORS 排查不要停留在“跨域了”这三个字上。先判断是否预检，再看预检响应，接着检查网关和凭证配置。把链路拆开以后，问题通常会从模糊的浏览器报错，变成某个具体响应头或某段代理配置。