“同一个接口,浏览器直接打开能返回,前端用 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 发起的跨源请求才受同源策略约束。这也是“浏览器能打开、代码却失败”的原因。
OPTIONS /api/orders HTTP/1.1
Origin: https://app.example
Access-Control-Request-Method: POST
Access-Control-Request-Headers: content-type, x-token服务端需要在响应里明确放行:
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: 600Max-Age 决定预检结果缓存多久;缓存期内不会重复发 OPTIONS。预检请求不会带 Cookie,真正的请求才带;服务端不要用预检里的 Cookie 判断登录态。Max-Age 还有浏览器上限(通常 600 秒左右),不要设成一天。
如果请求带 credentials: 'include',服务端不能把 Access-Control-Allow-Origin 设成 *,必须返回具体来源:
Access-Control-Allow-Origin: https://app.example
Access-Control-Allow-Credentials: true
Vary: OriginVary: 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 模拟预检:
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 删除。