CORS 跨域详解:从同源策略到 Spring Boot 配置与排错
前端页面运行在 http://localhost:5173,后端接口运行在 http://localhost:8080。
接口用 Postman 调试正常,放到浏览器里却出现:
Access to fetch at 'http://localhost:8080/api/orders'from origin 'http://localhost:5173' has been blocked by CORS policy.这时很容易直接给后端加一个 @CrossOrigin,直到登录、文件下载或者接入 Spring Security 后,再次遇到跨域报错。
要稳定地解决这类问题,需要知道浏览器检查什么,以及请求在哪一步失败。这篇以一个前后端分离的订单应用为例,把原理、配置和排错串起来。
一、先理解“跨域”里的源
对普通 HTTP / HTTPS 地址,源由三个部分组成:协议、主机、端口。三者相同才算同源,路径和查询参数不参与判断。MDN 同源策略 给出了对应的判定规则。
以 http://localhost:5173 为基准:
| 访问地址 | 是否同源 | 原因 |
|---|---|---|
http://localhost:5173/api/orders | 是 | 只有路径不同 |
http://localhost:5173/api/orders?page=2 | 是 | 查询参数不影响源 |
http://localhost:8080/api/orders | 否 | 端口不同 |
https://localhost:5173/api/orders | 否 | 协议不同 |
http://127.0.0.1:5173/api/orders | 否 | 主机不同 |
localhost 和 127.0.0.1 即使都指向本机,浏览器也不会把它们视为同一个源。生产环境的 https://www.example.com 和 https://api.example.com 同样跨域,因为主机不同。
同源策略限制一个源的脚本访问另一个源的资源。否则,用户打开一个陌生网页,这个网页就可能读取用户在其他网站上的私密数据。
这里需要区分:浏览器能发送某些跨域请求,并不代表页面脚本能读取它们的响应。 页面导航、图片加载、表单提交和 fetch 的规则也不完全相同,不能用“图片能加载”判断接口是否配置了 CORS。
二、CORS 到底解决什么问题
CORS 的全称是 Cross-Origin Resource Sharing,中文通常叫“跨源资源共享”。
它通过 HTTP 头告诉浏览器:哪些源可以读取这个接口的响应,以及允许使用哪些方法和请求头。
以读取订单列表为例,在运行于 http://localhost:5173 的页面中执行:
async function loadOrders() { const response = await fetch("http://localhost:8080/api/orders"); if (!response.ok) { throw new Error(`读取订单失败:${response.status}`); } return response.json();}
loadOrders().then(console.log).catch(console.error);浏览器发送的请求中会包含来源信息:
GET /api/orders HTTP/1.1Host: localhost:8080Origin: http://localhost:5173如果服务端允许这个源读取响应,可以返回:
HTTP/1.1 200 OKContent-Type: application/jsonAccess-Control-Allow-Origin: http://localhost:5173Vary: Origin
[{"id":1001,"status":"CREATED"}]浏览器检查这些头后,才把响应交给页面脚本。Origin 由浏览器管理,允许跨域的响应头应由服务端或网关设置。前端给请求加上 Access-Control-Allow-Origin,不会获得跨域权限,反而可能引入额外的预检。
协议定义见 WHATWG Fetch:CORS protocol。
为什么返回 200,前端还是报错
HTTP 请求成功和浏览器允许脚本读取响应是两件事。
服务端可能已经执行了查询,甚至已经创建订单,浏览器却因响应缺少正确的 CORS 头,把结果作为失败交给 fetch。因此,看到跨域错误时,不能立即认定后端没处理请求;对创建、支付等接口盲目重试,还可能造成重复操作。
Postman、普通命令行 curl 和服务端 HTTP 客户端不执行浏览器的同源策略,所以它们调用成功,只能证明接口在这些调用条件下可访问。
三、为什么有时先发一个 OPTIONS
跨域请求不一定直接发送业务请求。浏览器有时会先发出 预检请求(preflight),询问服务端是否接受接下来要使用的方法和请求头。
哪些请求通常不需要预检
日常说的“简单请求”,主要指满足 CORS 安全列表条件的请求。常见条件包括:
- 方法是
GET、HEAD或POST。 - 脚本设置的请求头满足安全列表规则,例如合规的
Accept、Accept-Language、Content-Language、Content-Type。 - 如果设置了
Content-Type,媒体类型是application/x-www-form-urlencoded、multipart/form-data或text/plain。
这些是常用判定条件,规范还限制部分头的值、长度,以及其他请求特征。现代安全列表也包含满足特定格式的单个 Range 范围,完整条件可查 MDN:简单请求。
例如,普通的订单列表 GET 通常直接发送。给同一个 GET 加上 Authorization,就通常需要预检;POST 如果发送 application/json,也通常需要预检。
“不需要预检”只意味着省掉前面的询问,实际响应仍然必须通过 CORS 检查。是否需要预检,也不能直接用来判断接口是否安全。
JSON POST 的完整过程
在前端页面中发送一个 JSON 订单:
async function createOrder() { const response = await fetch("http://localhost:8080/api/orders", { method: "POST", headers: { "Content-Type": "application/json", }, body: JSON.stringify({ productId: 101, quantity: 2 }), }); if (!response.ok) { throw new Error(`创建订单失败:${response.status}`); } return response.json();}在没有可用预检缓存的情况下,浏览器先发出:
OPTIONS /api/orders HTTP/1.1Host: localhost:8080Origin: http://localhost:5173Access-Control-Request-Method: POSTAccess-Control-Request-Headers: content-type服务端允许后返回,例如:
HTTP/1.1 204 No ContentAccess-Control-Allow-Origin: http://localhost:5173Access-Control-Allow-Methods: GET, POSTAccess-Control-Allow-Headers: Content-TypeAccess-Control-Max-Age: 600Vary: Origin, Access-Control-Request-Method, Access-Control-Request-Headers随后浏览器才发送实际的 POST。实际响应也需要 Access-Control-Allow-Origin;只让 OPTIONS 返回正确的头,业务响应仍然可能被拦截。
这里的 204 是一种常见的成功响应,合规的其他 2xx 状态也可以用于预检。
请求链路可以记成:
页面脚本发起 JSON POST → 浏览器发送 OPTIONS → 检查来源、方法、请求头是否获准 → 浏览器发送实际 POST → 再检查实际响应的 CORS 头 → 页面脚本读取结果如果预检没有通过,实际业务请求通常不会发送。如果实际请求已经发送,但响应检查没有通过,服务端可能已经完成业务操作。这是排查时最关键的分界。
四、常用 CORS 头怎么区分
| 头 | 所在位置 | 作用 |
|---|---|---|
Origin | 请求 | 当前页面的源 |
Access-Control-Request-Method | 预检请求 | 即将使用的业务方法 |
Access-Control-Request-Headers | 预检请求 | 即将使用的非安全列表请求头 |
Access-Control-Allow-Origin | 响应 | 允许读取响应的源 |
Access-Control-Allow-Methods | 预检响应 | 允许的业务方法 |
Access-Control-Allow-Headers | 预检响应 | 允许的请求头 |
Access-Control-Allow-Credentials | 响应 | 是否允许凭据模式为 include 的跨域响应被读取 |
Access-Control-Expose-Headers | 实际响应 | 额外开放给脚本读取的响应头 |
Access-Control-Max-Age | 预检响应 | 预检许可的缓存时间,单位为秒 |
预检缓存不同于普通业务响应缓存。浏览器可能对缓存时长设置上限,因此 maxAge 不是“接口数据多久更新”的配置。
一个响应只能指定一个源
下面这种写法不合法:
Access-Control-Allow-Origin: https://app.example.com, https://admin.example.com如果允许多个前端,服务端应维护允许列表,检查当前 Origin,再返回匹配的一个源。根据来源动态生成响应时,应正确设置 Vary: Origin,避免缓存把某个来源的响应直接用于另一个来源。
不要不经检查就把任意 Origin 原样回显,也不要用简单的字符串包含关系判断可信域名。
请求头获准,不等于响应头可读
下载报表时,服务端可能返回:
Content-Disposition: attachment; filename="orders.csv"X-Request-Id: order-export-1001Access-Control-Expose-Headers: Content-Disposition, X-Request-Id这时脚本才可以读取额外开放的头:
const filenameHeader = response.headers.get("Content-Disposition");const requestId = response.headers.get("X-Request-Id");这里的 response 指前面 fetch 得到的响应对象。Allow-Headers 管请求能带什么头,Expose-Headers 管脚本能读什么响应头,配置方向不同。
五、跨域携带 Cookie,需要同时满足哪些条件
假设订单接口使用 Session Cookie 登录。前端需要显式设置:
const response = await fetch("http://localhost:8080/api/orders", { credentials: "include",});fetch 默认的凭据模式是 same-origin。跨域时,仅配置后端 allowCredentials(true),不会让前端自动携带 Cookie。
服务端需要返回:
Access-Control-Allow-Origin: http://localhost:5173Access-Control-Allow-Credentials: trueVary: Origin当请求的凭据模式是 include,Access-Control-Allow-Origin 不能使用 *,即使当前请求恰好没有可发送的 Cookie,也受这个规则约束。带凭据的请求应明确列出允许的方法、请求头和开放的响应头;Authorization 还必须明确获准,不能指望 Allow-Headers: * 覆盖它。Fetch:CORS 与凭据 对此有明确规定。
跨域不一定跨站
源和站点是不同概念。前面两个 localhost 地址仅端口不同,属于跨域,但通常是同站;HTTPS 的 app.example.com 和 api.example.com 也可以跨域而同站。
所以,不能把“跨域请求”直接等同于“必须设置 SameSite=None”。Cookie 是否发送,还取决于适用的域、路径、Secure、SameSite 和浏览器策略。
如果确实需要在跨站的 fetch 请求中发送 Cookie,常见设置是:
Set-Cookie: SESSION=demo-session; Path=/; HttpOnly; Secure; SameSite=None这个头用于 HTTPS 部署示例,不能直接当作前面普通 HTTP 本地示例的 Cookie 配置。SameSite=None 要配合 Secure;浏览器的第三方 Cookie 限制仍可能阻止 Cookie 使用。MDN:Set-Cookie 说明了这些属性及限制。
Set-Cookie 本身不能通过前端 response.headers 读取,即使把它写进 Expose-Headers 也不行。调试 Cookie 应查看开发者工具的 Network 和 Cookie 存储面板。
六、Spring Boot 中如何配置
以下 Java 配置适用于使用 Servlet / Spring MVC 的 Spring Boot 项目,不适用于 WebFlux。配置类应放在应用启动类能够扫描到的包中。
普通 Spring MVC 项目
在已有 spring-boot-starter-web 项目中创建 WebCorsConfig.java:
import org.springframework.context.annotation.Configuration;import org.springframework.web.servlet.config.annotation.CorsRegistry;import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
@Configurationpublic class WebCorsConfig implements WebMvcConfigurer {
@Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping("/api/**") .allowedOrigins("http://localhost:5173") .allowedMethods("GET", "POST", "PUT", "DELETE") .allowedHeaders("Content-Type", "Authorization", "X-CSRF-TOKEN") .exposedHeaders("Content-Disposition", "X-Request-Id") .allowCredentials(true) .maxAge(600); }}这份配置对应本文的接口路径和本地前端端口。实际项目应按业务收紧方法和头;使用 PATCH 或其他自定义头时,再显式加入。
如果接口不需要跨域 Cookie,可以不启用 allowCredentials(true)。生产环境应把允许的来源换成实际 HTTPS 前端地址,避免直接沿用本地配置。
Spring 会处理匹配接口的预检,allowedMethods 主要配置实际业务请求的方法,不能把“只允许 OPTIONS”当成放行 POST。
少量接口也可以使用 @CrossOrigin,但项目中同时存在全局配置和局部注解时,需要理解它们的合并规则。配置方式见 Spring Framework:CORS。
接入 Spring Security 的项目
Spring Security 的过滤器通常在 Controller 之前执行。预检请求通常不携带登录 Cookie,如果先按普通业务请求校验登录状态,可能直接得到 401 或 403,MVC 层的跨域配置也就来不及处理。
在现有的 SecurityFilterChain 配置中启用 CORS,并为它提供明确的配置源。例如,在原有安全配置类中添加下面的 Bean 方法,需要引入列出的类型:
import java.util.List;import org.springframework.context.annotation.Bean;import org.springframework.web.cors.CorsConfiguration;import org.springframework.web.cors.UrlBasedCorsConfigurationSource;@BeanUrlBasedCorsConfigurationSource corsConfigurationSource() { CorsConfiguration config = new CorsConfiguration(); config.setAllowedOrigins(List.of("http://localhost:5173")); config.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE")); config.setAllowedHeaders(List.of( "Content-Type", "Authorization", "X-CSRF-TOKEN")); config.setExposedHeaders(List.of("Content-Disposition", "X-Request-Id")); config.setAllowCredentials(true); config.setMaxAge(600L);
UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource(); source.registerCorsConfiguration("/api/**", config); return source;}随后在原有 filterChain(HttpSecurity http) 方法中、http.build() 之前加入:
http.cors(cors -> cors.configurationSource(corsConfigurationSource()));这几段代码是对已有安全配置的增量修改,登录、接口权限和 CSRF 规则仍由该项目的安全配置负责。上面的 MVC 示例与这里的配置源是两种配置路径,采用后者时可统一在这里维护 CORS,避免重复定义。
仅允许所有 OPTIONS 通过认证,并不等于服务端会返回正确的 CORS 响应头。若有自定义 Token 过滤器,还要检查它是否在 CORS 处理前拒绝了预检。多个安全过滤链也需要分别确认配置。Spring Security:CORS 集成 解释了处理顺序和配置源的使用方式。
如果 OPTIONS 已通过,但实际 POST 返回 403,还应检查登录状态、接口权限和 CSRF 校验,不能继续把所有 403 都归因于跨域。
七、开发代理为什么能解决本地跨域
还有一种常见方式:浏览器访问当前前端服务的 /api,再由前端开发服务器转发到后端。
在使用 Vite 的前端项目里,可以在 vite.config.ts 中配置:
import { defineConfig } from "vite";
export default defineConfig({ server: { port: 5173, strictPort: true, proxy: { "/api": { target: "http://localhost:8080", changeOrigin: true, }, }, },});这份示例假设后端路径本来就是 /api/orders,因此不做路径重写。前端改为请求相对地址:
const response = await fetch("/api/orders");链路变成:
浏览器 → http://localhost:5173/api/ordersVite → http://localhost:8080/api/orders从浏览器视角,请求仍是同源。changeOrigin 调整的是代理发往上游的 Host 头,解决浏览器跨域的关键是前端访问了同源入口。
Vite 的 server.proxy 是开发服务器功能,不会随静态资源打包进生产部署,详见 Vite:server.proxy。上线时,如果继续采用同源入口,需要让 Nginx 或网关把 /api 转发到后端;如果浏览器直接访问另一个 API 源,则需要在那里配置 CORS。
如果仍然写 fetch("http://localhost:8080/api/orders"),请求会绕过 Vite 代理。代理场景下的 Cookie 域、路径和 HTTPS 属性,也要与浏览器实际访问的入口相匹配。
八、按请求链路排查跨域错误
先打开浏览器开发者工具的 Network 面板,保留请求记录,再复现问题。关注真正失败的 URL、状态码和响应头,不要只看 Console 的最后一行。
第一步:确认浏览器访问了哪个地址
核对页面源和接口地址。如果用了代理,检查浏览器请求是否仍指向后端绝对地址。还要留意 HTTP / HTTPS 混用、端口变化,以及接口是否被重定向到登录页面。
第二步:寻找预检请求
如果存在 OPTIONS,检查它携带的:
Origin: http://localhost:5173Access-Control-Request-Method: POSTAccess-Control-Request-Headers: content-type再检查响应是否允许这个源、方法和头,以及状态是否成功。只有状态 204,没有许可头,仍然不够。
如果看不到 OPTIONS,可能是不需要预检,也可能是浏览器复用了预检缓存,不能仅凭这一点判断配置没有生效。
第三步:检查实际业务响应
如果实际请求已经发出,检查它的响应头。登录失败、参数错误、服务异常和网关错误等响应,也应经过正确的 CORS 处理,否则前端可能只得到笼统的网络错误,读不到真正的错误信息。
同时检查响应由哪一层生成:后端已经配置 CORS,并不能自动覆盖由网关直接返回的 502 或认证失败响应。
第四步:如果使用 Cookie,检查发送条件
确认前端是否使用 credentials: "include",后端是否返回具体来源和 Allow-Credentials: true,Cookie 的属性是否匹配当前请求,以及浏览器是否提示 Cookie 被阻止。
常见现象对照
| 现象 | 优先检查 |
|---|---|
| Postman 正常,浏览器失败 | 浏览器的 Origin、预检与实际响应头 |
OPTIONS 返回 401 / 403 | Security、自定义过滤器、网关认证顺序 |
OPTIONS 成功,实际请求没发出 | Allow-Origin、Allow-Methods、Allow-Headers 是否匹配 |
实际响应 200,脚本仍读取失败 | 实际响应的 Allow-Origin、凭据规则、重复头 |
CORS 通过,实际 POST 返回 403 | 登录状态、接口权限、CSRF 校验 |
Network 有文件名,脚本读头得到 null | Expose-Headers 是否开放 Content-Disposition |
| 本地代理正常,上线失败 | 生产环境是否存在同源转发入口 |
后端和网关同时添加 CORS 头,也可能产生两个 Access-Control-Allow-Origin,使浏览器拒绝响应。明确由哪一层统一维护,会更容易排查。
使用 curl 检查响应头
如果自己的后端正在本机 8080 端口运行,可以手动模拟预检。下面使用 PowerShell 中的 curl.exe,避免与旧版 PowerShell 的 curl 别名混淆:
curl.exe -i -X OPTIONS "http://localhost:8080/api/orders" -H "Origin: http://localhost:5173" -H "Access-Control-Request-Method: POST" -H "Access-Control-Request-Headers: content-type"再检查实际 GET 的响应:
curl.exe -i "http://localhost:8080/api/orders" -H "Origin: http://localhost:5173"如果实际前端请求还带 Authorization 或 CSRF 头,模拟预检时也应把对应头名列入 Access-Control-Request-Headers。这些命令帮助检查服务端返回了什么,不会模拟浏览器的全部校验;最终需要在页面中验证。
九、几个容易走错的方向
mode: "no-cors" 不能让脚本读取 JSON
跨域 fetch 使用 no-cors 时,通常得到 opaque 响应,脚本不能读取其状态、头和正文,还会限制请求方法及可设置的头。它不适合“把接口返回的数据展示到页面”这种需求。
CORS 通过,不代表用户有权限
CORS 决定浏览器是否把跨源响应开放给脚本。登录校验和业务授权仍应由服务端执行,不能把 Origin 当作用户身份,也不能用来源允许列表代替订单归属校验。
CORS 也不能代替 CSRF 防护
某些不需要预检的跨站请求,可能在响应被阻止读取前就已经送到服务端并产生副作用。使用 Cookie 登录的业务,应根据实际场景配置 CSRF Token、SameSite 和其他校验;遇到 403 时先确定失败原因,再修改对应配置。
十、把配置放回实际场景
本地前后端分离调试,可以选择开发代理,也可以让后端允许实际的本地前端源。生产环境如果统一通过同一个站点入口访问页面和 /api,浏览器侧的接口调用可以保持同源;如果前端直接访问独立 API 源,就需要一套明确的 CORS 规则。
对使用 Cookie 的接口,同时检查前端凭据模式、后端许可头和 Cookie 属性。对带 JSON、自定义头或非安全列表方法的请求,先检查预检,再检查业务响应。
遇到报错时,先回答三个问题:请求发到了哪里,实际业务请求有没有发送,哪一层返回了缺失或不匹配的响应头。 这三个问题通常比反复添加跨域注解,更快定位问题。
If this article helped you, please share it with others!
Some information may be outdated






