HTTP预检请求（OPTIONS）原理与CORS跨域实战指南-代码聚汇网

HTTP预检请求（OPTIONS）原理与CORS跨域实战指南

CORS跨域预检请求

|难度：普通|阅读约 40 分钟

很多人第一次被OPTIONS请求卡住，都是在浏览器控制台看到一行红色的跨域报错，然后打开Network面板，发现一条莫名其妙的OPTIONS请求，状态码甚至是200，但真正的接口请求压根没发出去。那时候我刚工作不久，对着这行报错挠了一下午头，后来才搞明白，这不是后端接口挂了，也不是网络不通，而是浏览器在正式请求之前，先派了一个“隐形保安”去探路。这个保安就是HTTP预检请求。

这篇文章就围绕预检请求展开，把它的原理、触发规则、请求头响应头对应关系、后端怎么正确“放行”、以及常见的坑，一次讲透。无论你是前端调接口调到头大，还是后端被前端追问“为什么OPTIONS报错”，这篇都值得看完。

1. 预检请求是什么，为什么浏览器非要“多此一举”

1.1 同源策略：浏览器安全的地基

要理解预检请求，得先理解浏览器为什么要管跨域这件事。浏览器默认会执行“同源策略”，也就是一个页面只能读取“同源”的资源。所谓同源，是指协议、域名、端口三者完全一致。比如https://a.com:443下的页面，请求https://a.com:443/api是没问题的，但请求http://b.com:8080/api就被视为跨域。

这个策略的本质是保护用户。设想一下，如果你登录了银行网站，浏览器里留了银行的Cookie，然后你又打开了一个恶意网站，如果浏览器不限制跨域请求，恶意网站的脚本就能用你的Cookie去请求银行接口，修改密码、转账，后果不堪设想。所以浏览器默认不允许跨域读取响应，这是一道安全底线。

但现实中跨域又不可避免——前端静态资源放在CDN、后端API放在独立域名、本地开发环境跑着localhost:5173要调测试环境接口，到处都在跨域。所以浏览器又设计了CORS（跨域资源共享）机制，让服务器通过响应头显式声明“我允许某个跨域来源访问我的资源”。而预检请求，就是CORS机制里的一个前置环节。

1.2 简单请求和预检请求的分界线

并不是所有跨域请求都会触发预检。浏览器把跨域请求分成两类：简单请求和预检请求（非简单请求）。

简单请求必须同时满足三个条件：方法只能是GET、HEAD、POST；请求头只能使用CORS安全列表里的字段，比如Accept、Accept-Language、Content-Language、Content-Type且值只能是application/x-www-form-urlencoded、multipart/form-data、text/plain；请求不能使用XMLHttpRequest的withCredentials之外的自定义头部。实际开发中，只要请求头带了Authorization、X-Custom-Header，或者Content-Type用了application/json，这个请求就不属于简单请求了。

预检请求的处理逻辑很直接：浏览器先发一条OPTIONS请求，不带业务参数，只带上三个关键请求头——Origin说明来源、Access-Control-Request-Method说明将要使用的方法、Access-Control-Request-Headers说明将要携带的额外头部。浏览器根据服务器的回应来判断这个跨域请求是否被允许。如果服务器回复的响应头明确允许，浏览器才继续发真正的业务请求；如果服务器没有给出正确的CORS响应头，浏览器直接拦截。

用大白话总结：简单请求相当于找一个陌生管理员直接进去办业务，管理员看一眼觉得没问题就放行；预检请求相当于在进门前先问一句“我要带这些工具进去，可以吗？”，管理员点头了你才能进。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 预检请求的完整链路：从请求头到响应头

2.1 一条真实的OPTIONS请求长什么样

我随便拿一个实际开发中的例子拆解。假设前端部署在http://localhost:5173，后端接口在http://api.example.com，前端要发一个POST请求，Content-Type: application/json，还带一个自定义的X-Trace-ID请求头。

这时候浏览器会先发出这样一条预检请求：

code复制OPTIONS /api/user/login HTTP/1.1
Host: api.example.com
Origin: http://localhost:5173
Access-Control-Request-Method: POST
Access-Control-Request-Headers: content-type,x-trace-id

注意看，没有Cookie、没有请求体、没有业务参数，整个请求就干一件事：告诉服务器“我打算从http://localhost:5173向你的/api/user/login发一条POST请求，而且会带上content-type和x-trace-id这两个额外的头，你允许吗？”

服务器收到这条预检请求后，需要返回类似这样的响应头：

code复制HTTP/1.1 204 No Content
Access-Control-Allow-Origin: http://localhost:5173
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, X-Trace-ID
Access-Control-Max-Age: 86400

Access-Control-Allow-Origin告诉浏览器“我允许这个来源访问”，Access-Control-Allow-Methods和Access-Control-Allow-Headers分别对应前端询问的方法和头部。浏览器拿到这些响应头，逐项比对，全部匹配才会继续发真实请求。只要有一项不匹配，浏览器直接报CORS错误，比如常见的“Request header field x-trace-id is not allowed by Access-Control-Allow-Headers in preflight response”。

我见过很多后端新手直接返回200，但响应头里一个CORS字段都没有，这样就等于预检失败。预检请求的状态码其实不重要，重要的是CORS响应头有没有给到位。

2.2 预检缓存：preflight缓存为什么能大大提升性能

预检请求本身没有任何业务数据，但它依然占用一次网络往返。如果每次请求都要先发一次预检，整个页面的接口调用会多出将近一倍的请求数，性能损失很明显。

因此CORS规范设计了Access-Control-Max-Age响应头，表示预检结果可以缓存多少秒。举例来说，如果服务器返回：

code复制Access-Control-Max-Age: 86400

浏览器在86400秒（24小时）内再发起同样方法的跨域请求，就不会再发预检请求，而是直接用缓存的预检结果。这个值需要根据实际场景权衡：设太短，频繁预检增加请求量；设太长，后端如果频繁调整CORS策略，前端浏览器要等缓存过期才能生效。

我自己通常在生产环境设成86400（一天），开发环境设成600（十分钟）。这样既保证效率，又方便调试CORS策略变更。

2.3 预检失败时浏览器到底在拦截什么

很多前端同学有一个误解，觉得预检失败是服务器把请求拒了。其实预检失败时，那条真正的业务请求根本没有发出去，服务器压根没收到业务请求，一切都是浏览器单方面的拦截。

具体来说，浏览器的拦截分成两个环节：能否发送和能否读取。预检请求是“能否发送”的关卡——服务器没有明确允许，真实请求就不发。真实请求发出后，响应回来了，浏览器还会检查Access-Control-Allow-Origin是否匹配，不匹配的话即使是200响应，页面里的JS也读不到任何数据。这两个环节经常混在一起，排查时要分清楚。

实际调试时，我最常用的方法是打开浏览器DevTools的Network面板，过滤Fetch/XHR，如果看到一条状态码为200或204的OPTIONS请求下挂了一条灰色状态的POST请求，说明预检已经通过。如果只有一条OPTIONS，没有后续POST，那问题基本都出在预检环节。

3. 后端如何正确“放行”预检请求

3.1 方案选型：整体CORS策略还是单独拦截器处理

后端处理预检请求，有两种常见思路：一是交给框架或全局中间件统一处理，二是针对OPTIONS方法单独写接口。强烈建议选第一种，因为预检请求本质上是所有跨域接口共用的前置规则，单独写接口很容易漏掉路径匹配，还会让代码到处重复。

以Node.js的Express为例，最简单的全局限流中间件写法是这样：

javascript复制app.use((req, res, next) => {
  // 允许跨域的来源，生产环境这里应该配置成具体的域名列表
  res.setHeader('Access-Control-Allow-Origin', 'http://localhost:5173');
  // 如果允许携带Cookie，这里不能是 * 
  res.setHeader('Access-Control-Allow-Credentials', 'true');
  // 允许的请求方法
  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, PATCH, OPTIONS');
  // 允许的请求头，按实际需要配置
  res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, X-Trace-ID');
  // 预检结果缓存时间
  res.setHeader('Access-Control-Max-Age', '86400');

  // 如果是预检请求，直接结束响应
  if (req.method === 'OPTIONS') {
    res.status(204).end();
    return;
  }
  
  next();
});

这段代码关键的逻辑有两点：一是通过全局中间件的顺序，让每个接口在执行业务逻辑之前先完成CORS响应头设置；二是对OPTIONS方法直接返回204，不再继续走业务路由。业务代码里不需要为预检请求做任何额外处理。

Java生态里的Spring Boot则更简单，可以直接用@CrossOrigin注解，或者全局实现WebMvcConfigurer接口：

java复制@Configuration
public class CorsConfig implements WebMvcConfigurer {
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/**")
                .allowedOrigins("http://localhost:5173")
                .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS")
                .allowedHeaders("Content-Type", "Authorization", "X-Trace-ID")
                .maxAge(86400);
    }
}

也可以使用CorsFilter，效果相同。框架帮我们把预检请求的响应做了封装，但理解底层原理仍然很重要——因为你在实际项目中会遇到框架默认配置和自定义配置互相覆盖的情况。

3.2 关键参数怎么定：Allow-Origin、Allow-Headers、Allow-Methods

这三个响应头是预检是否通过的核心判据，配置时各有讲究。

Access-Control-Allow-Origin要格外小心。生产环境千万不要图省事直接写*，尤其是在接口需要携带Cookie的场景下。根据CORS规范，Access-Control-Allow-Credentials: true和Access-Control-Allow-Origin: *不能同时出现，如果两者都设置了，浏览器会直接报错。正确做法是设成具体的请求来源，或者用逻辑动态匹配。

Access-Control-Allow-Headers要和前端实际发送的请求头对应上。前端发送的每个非安全列表请求头，都必须出现在这个值里。命名上不区分大小写，但内容必须匹配。前端如果发送了Content-Type: application/json，预检请求里Access-Control-Request-Headers就会有content-type，后端Allow-Headers也要包含content-type或者Content-Type。

Access-Control-Allow-Methods同理，前端要发PUT方法，这个字段就必须包含PUT。另外建议把OPTIONS永远加进去，虽然很多框架默认支持，但自己显式声明能省掉一些奇怪的问题。

3.3 反向代理能消除预检吗

很多人会想到，既然跨域问题这么麻烦，我用Nginx把前端和后端放到同一个域名下，是不是就没有预检请求了？

是的，如果前端页面和后端API最终同源，就没有跨域，浏览器自然不做预检。Nginx里只需要把/api路径代理到后端服务：

nginx复制server {
    listen 80;
    server_name www.example.com;

    location /api/ {
        proxy_pass http://backend-server:8080/api/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

这样的方案能解决大部分“前端调自己的后端接口”的跨域问题，而且从根上避免了预检。但要注意几点：一是本地开发经常还是会跨域，因为前端跑在localhost:5173，后端如果用Nginx代理，也得保证开发环境的前端能访问到代理网关；二是如果前端要调用的是第三方API（比如地图服务、支付服务），你没法给别人的服务器配Nginx，只能在服务端做中转；三是某些浏览器安全策略较严的场景，代理配置不对还是会暴露CORS问题。

我个人建议是：如果项目掌控全栈，优先用Nginx同源方案；如果前端要对接多个后端团队，或者有第三方API，直接用CORS预检加上后端统一放行更灵活。

4. 常见问题与排查技巧实录

4.1 预检请求报404或403

预检请求发到服务器后返回404，最常见的原因是后端路由没匹配到OPTIONS方法。比如Spring Boot的@RequestMapping没有指定method = RequestMethod.OPTIONS，或者Express的路由只注册了POST方法，OPTIONS就会被当成不存在的路径。

排查思路很简单：打开DevTools看那条预检请求的响应状态。如果404，说明你的服务端框架层面就把预检请求挡了；如果403，可能是服务器配置了额外的安全策略，比如WAF规则、鉴权插件拦截了OPTIONS请求。我在实际项目中遇到过Web应用防火墙把OPTIONS请求当成扫描攻击拦截的情况，需要在防火墙规则里放行OPTIONS方法。

4.2 预检请求返回200但报错“Request header field is not allowed”

这个报错信息在CORS错误里非常典型。报错说明预检请求已经到达服务器、服务器也已经返回了200，但返回的Access-Control-Allow-Headers里没有包含前端请求的那个自定义头。

举例说明：前端请求头里有Authorization，但后端配置的是Access-Control-Allow-Headers: Content-Type，浏览器比对后发现Authorization不在允许列表里，就会报这个错。解决办法就是对齐前后端的请求头字段。

这里有个容易踩的细节：前端如果使用了axios，它默认的请求头里可能带有X-Requested-With这个字段，有些后端配置的Allow-Headers没包含它，也会导致预检失败。如果前端代码里没有显式设置X-Requested-With，但axios自动加上了，你需要检查实际发出的预检请求Access-Control-Request-Headers里到底是哪些字段，再逐一对齐。

4.3 预检成功但真实请求的响应头缺失或不对

这类问题更隐蔽：预检通过了，真实请求也发了，服务器也正常处理了，但响应里没有Access-Control-Allow-Origin，或者返回的Access-Control-Allow-Origin是另一个域名，浏览器依然会把响应拦截，控制台会报类似“No ‘Access-Control-Allow-Origin’ header is present on the requested resource”的错。

真实请求和预检请求对响应头的要求是独立的。预检通过只代表“允许发送”，但真实响应回来时，浏览器还要再次检查Access-Control-Allow-Origin是否匹配。所以在后端全局中间件里，CORS响应头的设置必须对所有请求生效，不只是OPTIONS请求。这一点在压测或自测时容易被忽略——你用curl直接调接口能看到返回数据，但浏览器里就是不行，因为curl不会执行CORS检查。

调试这类问题时，我建议用curl手动模拟预检流程。比如：

bash复制curl -i -X OPTIONS 'http://api.example.com/api/user/login' \
  -H 'Origin: http://localhost:5173' \
  -H 'Access-Control-Request-Method: POST' \
  -H 'Access-Control-Request-Headers: Content-Type, X-Trace-ID'

然后检查返回的响应头是否完整，再对比DevTools里的实际响应和浏览器拦截的差异。这个方法能帮助确认问题到底在服务器配置，还是浏览器解析。

4.4 带Cookie的跨域请求为什么总是失败

跨域请求带Cookie，是另一个让人头疼的场景。前端需要把withCredentials设为true，后端必须返回Access-Control-Allow-Credentials: true，而且Access-Control-Allow-Origin不能是*。

这两条缺一不可。前端没有开启withCredentials，浏览器不会携带Cookie；后端没有返回Allow-Credentials，浏览器直接拒绝读取响应。具体来说，Cookie的写操作不在CORS检查范围内，但读取响应数据会被拦截，所以你会看到请求状态可能是200但responseText为空。

另外要注意Cookie本身的SameSite属性。现代浏览器默认SameSite=Lax，跨站请求很多情况下不会带Cookie，这时候光配置CORS还不够，需要后端在设置Cookie时显式指定：

code复制Set-Cookie: session_id=xxx; Path=/; SameSite=None; Secure

SameSite=None表示允许跨站携带，但必须配合Secure，也就是只能通过HTTPS传输。这个属性很容易被忽略，我遇到过好几回CORS配置和withCredentials都对了，最后发现是SameSite拦了一道，还折腾了挺久。

4.5 预检请求太多，影响接口性能怎么办

如果页面初始化时一口气发了十几个跨域请求，每条都触发预检，那种“一串OPTIONS后跟一串POST”的请求瀑布流确实看着让人焦虑。优化方式有两个方向。

第一个方向是设置Access-Control-Max-Age，让浏览器缓存预检结果，避免每次请求都重新预检。这个设置对GET和POST这类同样方法、同样请求头的请求生效。

第二个方向是从设计层面减少触发预检的可能。比如把多个请求头合并成一个签名头，或者把请求方法限制在POST内，Content-Type尽量用application/x-www-form-urlencoded，这样至少有一部分请求可以变成简单请求，不触发预检。但需要注意，为了省一次预检而牺牲接口设计本身，不值得。大多数情况下，预检请求的额外开销远小于一次完整的业务请求，设置好Max-Age就够了。

4.6 常见问题速查表

现象	可能原因	排查建议
预检请求404	后端路由未注册`OPTIONS`方法	检查路由配置，或交给全局中间件处理
预检请求403	防火墙/WAF拦截了`OPTIONS`	检查安全策略，放行`OPTIONS`
报错“header field is not allowed”	请求头不在`Allow-Headers`里	对照`Access-Control-Request-Headers`逐项配置
真实请求响应头缺失`Allow-Origin`	只对预检设置了CORS头	把所有响应统一设置CORS头
带Cookie跨域失败	`Allow-Origin: *`或`SameSite`问题	设置具体Origin和`Allow-Credentials`，检查Cookie属性
预检频繁	未设置`Max-Age`	设置`Access-Control-Max-Age`

5. 从预检请求到CORS整体排查思路

5.1 排查跨域问题时的标准动作

遇到跨域报错，不要急着改代码。我个人的排查顺序是固定的，照着走能省下大量时间。

第一步，在DevTools里找到那条报错的请求，确定它属于预检失败还是真实请求失败。预检失败的报错信息里通常会包含“preflight”字样；真实请求失败的报错信息里会缺少CORS响应头的具体提示。

第二步，用curl直接看服务器初始响应。不带任何Origin信息的请求和带Origin的请求，服务器可能返回不同的响应头，因为有些代码里是根据请求来源动态设置Access-Control-Allow-Origin的。所以模拟时要尽量还原浏览器发出的请求头。

第三步，对比前端实际请求头和服务端允许的字段。我会把Access-Control-Request-Headers的内容列出来，对照Access-Control-Allow-Headers逐一比对，大小写忽略，字段必须存在。

第四步，检查全局和局部配置是否有覆盖关系。比如某个接口单独配置了@CrossOrigin(origins = "http://localhost:5173")，而全局配置的是*，接口级别配置往往优先，可能导致开关不一致。

5.2 前端开发环境的特殊处理

开发环境下，很多人用的是Vite或webpack-dev-server的proxy代理方案，通过本地服务转发请求，避免浏览器直接跨域。这个方案在开发时挺方便，但有一个坑：如果后端接口返回的重定向或资源地址是绝对路径，代理转发时不一定能正确改写，访问就可能异常。

Vite的配置比较简单：

javascript复制export default defineConfig({
  server: {
    proxy: {
      '/api': {
        target: 'http://api.example.com',
        changeOrigin: true
      }
    }
  }
})

changeOrigin: true会把请求头里的Host改成目标域名，这样后端做域名校验时不会被卡住。

但要注意，这套proxy只在开发服务器层面生效，构建产物部署到Nginx或其他生产环境后，还得靠Nginx代理或后端CORS配置兜底。很多团队开发时用proxy掩盖了跨域问题，部署上线后才暴露，建议在开发阶段就保持和线上一致的跨域策略，避免两套环境行为不一致。

5.3 安全配置的边界

预检请求本身不携带业务数据，所以服务器响应预检时，只需要返回CORS相关头即可，不要执行业务逻辑，也不要做鉴权验证。如果服务器在处理预检请求时要求携带Authorization头，而预检请求默认不带Cookie也不带业务鉴权头，这个接口的跨域请求就永远不可能通过。这是一个安全设计问题——预检请求是浏览器在发业务请求之前做的询问，它就是一个不带凭据的询问请求。

另外，服务器应该有意识地限制Access-Control-Allow-Origin，避免用*加Allow-Credentials: true这种危险组合。攻击者可以构造一个恶意网页，用受害者的浏览器向目标接口发起跨域请求如果服务端配置过于开放，存在被恶意利用的风险。把允许的来源限制到可信域名白名单，是成本最低的安全做法。

我在实际项目里通常会把允许来源做成一个配置项，比如根据请求头里的Origin动态查询白名单，命中才返回对应的Access-Control-Allow-Origin，否则不返回CORS头。这样既支持多环境（本地、测试、生产不同来源），又不会把所有人都放进来。

6. 预检请求之外：CORS的其他边界情况

6.1 非浏览器场景为什么没有预检

很多人会好奇，我用curl调用后端接口一切正常，用Postman调用也正常，为什么一到浏览器就出问题？

原因很简单：预检请求是浏览器特有的行为。curl、Postman、服务端代码发起HTTP请求时，完全没有同源策略的概念，也不会执行CORS检查。它们是“想要什么就直接请求什么”，服务器返回什么它就接收什么。浏览器则像一个谨慎的管家，先问清楚再放行，回来还要再检查一遍。

这带来一个很实用的经验：跨域问题只能在浏览器里排查，其他工具的调用结果不具备参考价值。如果后端同事说他用Postman测过没问题，你可以回一句“浏览器管得严”，然后把DevTools的报错截图发给他，效率更高。

6.2 其他跨域方案的取舍

除了CORS预检和同源代理，还有两种常见的跨域方案：JSONP和postMessage。JSONP利用<script>标签天然不受同源限制的特性，通过动态插入script标签来加载数据，但它只支持GET请求，而且存在安全风险，现在基本只用于一些老旧的第三方接口。postMessage主要用于跨窗口消息传递，比如iframe通信，在特定场景下很实用。

技术选型时的建议只有一条：新项目优先使用标准的CORS方案，它是目前浏览器支持最好、最成熟、安全性最可控的跨域方案。JSONP当做历史遗留问题处理，postMessage只用于窗口通信。

6.3 框架和浏览器版本对预检行为的影响

不同的浏览器对预检请求的缓存策略和报错信息格式略有差异，但核心行为都遵循CORS规范，没有本质区别。Chrome的报错信息最详细，Edge和Safari相对简略，Firefox的报错信息里也会给出具体缺失的响应头名称。

框架层面，有些HTTP库会自动处理或修改请求头。比如axios在浏览器里使用XMLHttpRequest对象，如果你传了Content-Type: application/json，它会自动在预检请求里带上content-type；如果你用fetch，默认情况下不带凭据，需要显式设置credentials: 'include'。这些细节在遇到“为什么同样的代码在这个项目里不报错、在另一个项目里报错”时，偶尔就是罪魁祸首。

7. 一点实操心得

做了一堆跨域相关的项目之后，我发现大多数预检请求问题其实不是原理复杂，而是前后端信息不对齐。前端看到报错，以为是后端接口的问题；后端看日志，发现预检根本没到业务代码或者直接返回了200，两边各说各话，问题就卡住了。

现在我处理这类问题的习惯是：先把责任边界划分清楚——预检请求归浏览器管，CORS响应头归后端管，请求头匹配归前端管。前端确认Access-Control-Request-Headers的字段，后端确认Access-Control-Allow-Headers的配置，两边一对齐，80%的问题当场就能定位。剩下的20%，基本是代理、Cookie、防火墙之类的环境问题，按上面的排查顺序一步步就能找到。

最后分享一个小技巧：如果跨域问题实在纠缠不清，可以在后端临时加一个响应日志中间件，专门打印关键CORS头的值和收到的Origin、Access-Control-Request-Headers。这比在浏览器断点调试要直观得多，很多诡异问题都是靠这种“服务器视角的日志”找到原因的。这个习惯我一直用到现在。