mobile wallpaper 1mobile wallpaper 2mobile wallpaper 3mobile wallpaper 4
4461 words
12 minutes
CORS 跨域详解:从同源策略到 Spring Boot 配置与排错
2026-10-14

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.1
Host: localhost:8080
Origin: http://localhost:5173

如果服务端允许这个源读取响应,可以返回:

HTTP/1.1 200 OK
Content-Type: application/json
Access-Control-Allow-Origin: http://localhost:5173
Vary: 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.1
Host: localhost:8080
Origin: http://localhost:5173
Access-Control-Request-Method: POST
Access-Control-Request-Headers: content-type

服务端允许后返回,例如:

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: http://localhost:5173
Access-Control-Allow-Methods: GET, POST
Access-Control-Allow-Headers: Content-Type
Access-Control-Max-Age: 600
Vary: 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-1001
Access-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:5173
Access-Control-Allow-Credentials: true
Vary: 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;
@Configuration
public 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;
@Bean
UrlBasedCorsConfigurationSource 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/orders
Vite → 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:5173
Access-Control-Request-Method: POST
Access-Control-Request-Headers: content-type

再检查响应是否允许这个源、方法和头,以及状态是否成功。只有状态 204,没有许可头,仍然不够。

如果看不到 OPTIONS,可能是不需要预检,也可能是浏览器复用了预检缓存,不能仅凭这一点判断配置没有生效。

第三步:检查实际业务响应#

如果实际请求已经发出,检查它的响应头。登录失败、参数错误、服务异常和网关错误等响应,也应经过正确的 CORS 处理,否则前端可能只得到笼统的网络错误,读不到真正的错误信息。

同时检查响应由哪一层生成:后端已经配置 CORS,并不能自动覆盖由网关直接返回的 502 或认证失败响应。

第四步:如果使用 Cookie,检查发送条件#

确认前端是否使用 credentials: "include",后端是否返回具体来源和 Allow-Credentials: true,Cookie 的属性是否匹配当前请求,以及浏览器是否提示 Cookie 被阻止。

常见现象对照#

现象优先检查
Postman 正常,浏览器失败浏览器的 Origin、预检与实际响应头
OPTIONS 返回 401 / 403Security、自定义过滤器、网关认证顺序
OPTIONS 成功,实际请求没发出Allow-Origin、Allow-Methods、Allow-Headers 是否匹配
实际响应 200,脚本仍读取失败实际响应的 Allow-Origin、凭据规则、重复头
CORS 通过,实际 POST 返回 403登录状态、接口权限、CSRF 校验
Network 有文件名,脚本读头得到 nullExpose-Headers 是否开放 Content-Disposition
本地代理正常,上线失败生产环境是否存在同源转发入口

后端和网关同时添加 CORS 头,也可能产生两个 Access-Control-Allow-Origin,使浏览器拒绝响应。明确由哪一层统一维护,会更容易排查。

使用 curl 检查响应头#

如果自己的后端正在本机 8080 端口运行,可以手动模拟预检。下面使用 PowerShell 中的 curl.exe,避免与旧版 PowerShell 的 curl 别名混淆:

Terminal window
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 的响应:

Terminal window
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、自定义头或非安全列表方法的请求,先检查预检,再检查业务响应。

遇到报错时,先回答三个问题:请求发到了哪里,实际业务请求有没有发送,哪一层返回了缺失或不匹配的响应头。 这三个问题通常比反复添加跨域注解,更快定位问题。

Share

If this article helped you, please share it with others!

CORS 跨域详解:从同源策略到 Spring Boot 配置与排错
https://mizuki.mysqil.com/posts/cors-cross-origin-guide/
Author
梦幻晨风
Published at
2026-10-14
License
CC BY-NC-SA 4.0

Some information may be outdated

Table of Contents