首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >CORS 预检请求:为什么简单请求能过,带自定义头的请求却失败

CORS 预检请求:为什么简单请求能过,带自定义头的请求却失败

原创
作者头像
跨境出海观察员
发布于 2026-11-16 09:05:27
发布于 2026-11-16 09:05:27
120
举报

“同一个接口,浏览器直接打开能返回,前端用 fetch 就报 CORS 错误。”这类问题通常不是接口挂了,而是请求触发了预检,服务端没有正确响应 OPTIONS。CORS 不是一道开关,而是一组请求/响应头的协商。

一、简单请求与预检

浏览器把跨源请求分成两类。简单请求只允许 GET、HEAD、POST,并且只能使用少量安全头(如 Accept、Content-Type 的 text/plain、multipart/form-data、application/x-www-form-urlencoded)。

一旦用了 Content-Type: application/json、自定义头(如 X-Token)或 PUT/DELETE,浏览器会先发一个 OPTIONS 预检,询问服务端“允不允许这个跨源请求”。简单请求不是“没有 CORS”,而是浏览器直接发请求,再根据响应头决定是否把结果交给 JS;预检则是先问再发。

直接在地址栏打开接口,是顶层导航,不受 CORS 限制;fetch 发起的跨源请求才受同源策略约束。这也是“浏览器能打开、代码却失败”的原因。

代码语言:http
复制
OPTIONS /api/orders HTTP/1.1
Origin: https://app.example
Access-Control-Request-Method: POST
Access-Control-Request-Headers: content-type, x-token

服务端需要在响应里明确放行:

代码语言:http
复制
Access-Control-Allow-Origin: https://app.example
Access-Control-Allow-Methods: POST, OPTIONS
Access-Control-Allow-Headers: content-type, x-token
Access-Control-Max-Age: 600

Max-Age 决定预检结果缓存多久;缓存期内不会重复发 OPTIONS。预检请求不会带 Cookie,真正的请求才带;服务端不要用预检里的 Cookie 判断登录态。Max-Age 还有浏览器上限(通常 600 秒左右),不要设成一天。

二、带 Cookie 的跨源请求

如果请求带 credentials: 'include',服务端不能把 Access-Control-Allow-Origin 设成 *,必须返回具体来源:

代码语言:http
复制
Access-Control-Allow-Origin: https://app.example
Access-Control-Allow-Credentials: true
Vary: Origin

Vary: Origin 很重要。如果 CDN 或代理缓存了某个来源的响应,其他来源可能拿到错误的 CORS 头。不要为了省事把任意 Origin 原样反射回去,这会放大跨站请求风险;应该用白名单校验。Origin 头由浏览器自动添加,JS 不能伪造;服务端不要相信前端传的 Origin 参数。

Access-Control-Expose-Headers 决定 JS 能读到哪些响应头;默认只能读 Cache-Control、Content-Language、Content-Type 等少数几个。自定义 X-Request-Id 要显式 expose。

三、常见失败原因

第一,服务端没有处理 OPTIONS,直接返回 404/405。预检失败,真正的请求不会发出。

第二,Access-Control-Allow-Headers 漏了自定义头。前端加了 X-Token,服务端只放行 content-type,预检就会失败。Access-Control-Allow-Methods 也必须包含实际方法和 OPTIONS;只写 POST 不写 OPTIONS,预检会失败。头名大小写不敏感,但值要匹配。

第三,Allow-Origin 用了 *,但请求带了 Cookie。浏览器会拒绝。

第四,重定向。预检请求遇到 301/302 可能失败;跨源请求的重定向要谨慎。

第五,网关或 WAF 拦截了 OPTIONS。本地开发正常、线上失败,通常是这一层。

Access-Control-Allow-Origin 必须是完整 origin(协议+域名+端口),不能带路径;多个来源要动态返回匹配的那个,或配置多个响应头(部分服务器支持)。本地开发常用代理把跨源变成同源,线上直连才触发 CORS;这不是代码回退,而是环境差异。

四、怎么排查

第一,看 Network 里有没有 OPTIONS 请求,状态码是多少。

第二,看预检响应头是否包含 Allow-Origin、Allow-Methods、Allow-Headers。

第三,用 curl 模拟预检:

代码语言:bash
复制
curl -i -X OPTIONS https://api.example/orders \
  -H 'Origin: https://app.example' \
  -H 'Access-Control-Request-Method: POST' \
  -H 'Access-Control-Request-Headers: content-type, x-token'

第四,对比简单请求和带自定义头的请求,确认是不是预检环节失败。

五、总结

CORS 的关键是“预检协商”:浏览器先问,服务端明确答,真正的请求才会发出。排查时先看 OPTIONS,再看 Allow-* 头,最后才怀疑业务代码。带 Cookie 的场景不要用 *,白名单加 Vary: Origin 更稳。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 一、简单请求与预检
  • 二、带 Cookie 的跨源请求
  • 三、常见失败原因
  • 四、怎么排查
  • 五、总结
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档