Spring Boot跨域处理方案
跨域不是“后端报了一个错”,而是浏览器基于同源策略拦截了响应或请求。解决问题也不是简单加一个通配符,而是明确允许哪些来源、方法、请求头和凭据,并让预检请求安全地通过完整调用链。
上一篇《Spring Boot拦截器与过滤器实战》梳理了 Filter 与 HandlerInterceptor 的职责边界。本文继续处理 Web 联调中的高频问题:为什么后端接口实际执行了,前端仍然拿不到结果,以及 Spring MVC、CorsFilter 和 Spring Security 应如何配合。
环境说明:示例基于 Spring Boot 3.x、Spring Framework 6、Java 17 和 Servlet Web 应用。Spring Security 示例使用
SecurityFilterChain配置方式。CORS 是浏览器机制,不等于身份认证,也不能替代 CSRF 防护、接口鉴权或服务端访问控制。
一、先理解同源策略
浏览器判断两个 URL 是否同源,主要比较三项:
协议,例如
http与https;主机名,例如
localhost与api.example.com;端口,例如
8080与5173。
以下页面与接口均不同源:
同源策略限制的是网页中的脚本如何读取跨源响应,不是禁止服务器之间通信。因此,使用 curl、Postman 或另一个后端服务请求接口成功,并不能证明浏览器跨域配置正确。
还要区分两个概念:
请求没有到达后端:可能被代理、网络、安全规则或预检失败阻断;
后端已经执行并返回:也可能因缺少正确 CORS 响应头,浏览器不把响应交给前端 JavaScript。
排查时应同时查看浏览器 Console、Network 和后端日志,不要只看其中一处。
二、CORS 如何工作
CORS 即跨源资源共享。浏览器通过在请求中携带 Origin,让服务器声明允许哪些跨源访问。
一个基本请求可能包含:
Origin: http://localhost:5173服务器响应:
Access-Control-Allow-Origin: http://localhost:5173浏览器确认响应头与页面来源匹配后,才把响应交给前端代码。
常见响应头包括:
这些头不是越多越好,而应与实际接口需求一致。
三、什么是预检请求
当请求不属于浏览器定义的简单请求范围时,浏览器通常会先发送 OPTIONS 预检请求。例如:
使用
PUT、PATCH、DELETE等方法;携带
Authorization等自定义请求头;使用某些非简单请求范围内的
Content-Type,例如application/json。
预检请求类似:
OPTIONS /api/users/1 HTTP/1.1
Host: localhost:8080
Origin: http://localhost:5173
Access-Control-Request-Method: PUT
Access-Control-Request-Headers: authorization,content-type服务端允许时返回对应响应头:
Access-Control-Allow-Origin: http://localhost:5173
Access-Control-Allow-Methods: PUT
Access-Control-Allow-Headers: authorization,content-type预检通过后,浏览器才继续发送真正的 PUT 请求。
因此,以下情况很常见:
后端日志只有
OPTIONS,没有业务请求;Controller 中的
PUT没有执行;自定义拦截器拒绝了
OPTIONS;安全组件要求预检请求也必须登录。
预检不是前端多余发送的请求,也不应该在 Controller 中为每个接口手写一个 OPTIONS 方法。
四、最小方案:使用 @CrossOrigin
如果只有少量 Controller 或方法需要跨域,可以使用 @CrossOrigin。
import org.springframework.web.bind.annotation.CrossOrigin;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/api/articles")
@CrossOrigin(origins = "http://localhost:5173")
public class ArticleController {
@GetMapping("/{id}")
public ArticleResponse detail(Long id) {
return new ArticleResponse(id, "Spring Boot CORS");
}
}
record ArticleResponse(Long id, String title) {
}也可以只标注某个方法:
@CrossOrigin(
origins = "http://localhost:5173",
methods = RequestMethod.GET,
maxAge = 3600
)
@GetMapping("/public")
public String publicContent() {
return "public";
}方法级配置适合局部例外,类级配置适合整个 Controller 使用同一规则。实际项目应明确指定环境对应的来源,不要照搬开发地址到生产环境。
@CrossOrigin 简单直观,但规则散落在多个 Controller 后,统一审查和环境管理会变得困难。接口较多时,通常优先考虑全局配置。
五、全局配置:WebMvcConfigurer
Spring MVC 项目可以通过 WebMvcConfigurer 集中配置:
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",
"https://app.example.com"
)
.allowedMethods("GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS")
.allowedHeaders("Content-Type", "Authorization", "X-Request-Id")
.exposedHeaders("X-Request-Id")
.allowCredentials(true)
.maxAge(3600);
}
}这段配置只处理 /api/** 路径,并允许两个明确来源。不要为了让报错消失而直接开放全部路径、全部来源和全部请求头。
5.1 allowedOrigins 与 allowedOriginPatterns
allowedOrigins 使用精确来源:
.allowedOrigins("https://app.example.com")allowedOriginPatterns 支持模式匹配,例如同一组织下有限范围的域名:
.allowedOriginPatterns("https://*.example.com")模式匹配不等于可以忽略安全边界。尤其携带 Cookie 或认证凭据时,应使用明确、可审计的允许列表,不要配置 * 后再开启凭据。
5.2 通配符与凭据不能随意组合
下面这种设计不符合凭据场景的要求:
// 不推荐:允许任意来源并携带凭据,既危险又可能无法正常工作
registry.addMapping("/api/**")
.allowedOrigins("*")
.allowCredentials(true);跨源 Cookie 或凭据模式下,响应不能使用任意来源通配符代替明确的允许来源。即使某些 API 支持 allowedOriginPatterns("*") 与凭据组合,也不代表“反射任意 Origin 并允许凭据”是安全设计。
六、凭据、Authorization 与 Cookie 要分开理解
开启:
.allowCredentials(true)主要影响浏览器的凭据模式以及 Access-Control-Allow-Credentials 响应。它并不意味着所有请求都自动登录,也不意味着可以放开任意来源。
前端使用 Cookie 会话时,还可能需要:
fetch('http://localhost:8080/api/me', {
credentials: 'include'
})如果前端使用 Authorization 请求头,则还需要:
后端允许
Authorization请求头;预检请求能够通过;
真正的业务请求仍然完成认证;
不把访问令牌写入不安全的日志。
跨站 Cookie 还受 SameSite、Cookie 属性和浏览器第三方 Cookie 策略影响。需要跨站发送 Cookie 时,通常涉及 SameSite=None; Secure,并应同步评估 CSRF 风险。CORS 配置正确,不代表浏览器一定接受或发送 Cookie。
七、使用 CorsFilter 统一处理
当需要让 CORS 处理发生在更靠前的过滤器链路,或与 CorsConfigurationSource 统一管理时,可以注册 CorsFilter:
import java.util.List;
import org.springframework.boot.web.servlet.FilterRegistrationBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.Ordered;
import org.springframework.web.cors.CorsConfiguration;
import org.springframework.web.cors.UrlBasedCorsConfigurationSource;
import org.springframework.web.filter.CorsFilter;
@Configuration
public class CorsFilterConfig {
@Bean
FilterRegistrationBean<CorsFilter> corsFilterRegistration() {
CorsConfiguration config = new CorsConfiguration();
config.setAllowedOrigins(List.of(
"http://localhost:5173",
"https://app.example.com"
));
config.setAllowedMethods(List.of(
"GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"
));
config.setAllowedHeaders(List.of(
"Content-Type", "Authorization", "X-Request-Id"
));
config.setExposedHeaders(List.of("X-Request-Id"));
config.setAllowCredentials(true);
config.setMaxAge(3600L);
UrlBasedCorsConfigurationSource source =
new UrlBasedCorsConfigurationSource();
source.registerCorsConfiguration("/api/**", config);
FilterRegistrationBean<CorsFilter> registration =
new FilterRegistrationBean<>(new CorsFilter(source));
registration.setOrder(Ordered.HIGHEST_PRECEDENCE);
return registration;
}
}CorsFilter 可以在符合配置的预检请求到达 Controller 之前完成处理。设置较早的顺序也有助于避免自定义过滤器提前拒绝预检。
但不要同时维护多套相互重叠的规则:
WebMvcConfigurer全局映射;独立
CorsFilter;Spring Security 的
CorsConfigurationSource;网关或 Nginx 再添加一遍相同响应头。
重复配置可能导致策略难以判断,甚至产生重复的 Access-Control-Allow-Origin 响应头。选择一个主要配置层,并明确其他层是否只透传。
八、与 Spring Security 配合
引入 Spring Security 后,只添加 @CrossOrigin 往往不够。安全过滤器可能在 MVC CORS 处理之前拦截请求,尤其是 OPTIONS 预检。
推荐在 Security 配置中启用 CORS,并提供一个明确的 CorsConfigurationSource:
import java.util.List;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.Customizer;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.web.cors.CorsConfiguration;
import org.springframework.web.cors.CorsConfigurationSource;
import org.springframework.web.cors.UrlBasedCorsConfigurationSource;
@Configuration
public class SecurityConfig {
@Bean
SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
http
.cors(Customizer.withDefaults())
.authorizeHttpRequests(authorize -> authorize
.requestMatchers("/api/public/**").permitAll()
.anyRequest().authenticated()
);
return http.build();
}
@Bean
CorsConfigurationSource corsConfigurationSource() {
CorsConfiguration config = new CorsConfiguration();
config.setAllowedOrigins(List.of(
"http://localhost:5173",
"https://app.example.com"
));
config.setAllowedMethods(List.of(
"GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"
));
config.setAllowedHeaders(List.of(
"Content-Type", "Authorization", "X-Request-Id"
));
config.setAllowCredentials(true);
config.setMaxAge(3600L);
UrlBasedCorsConfigurationSource source =
new UrlBasedCorsConfigurationSource();
source.registerCorsConfiguration("/api/**", config);
return source;
}
}Spring Security 会在容器中找到 CorsConfigurationSource 并将其用于 CORS 处理。这样预检可以经过 Security 的 CORS 支持,而真正的业务请求仍由授权规则保护。
不要为了让预检通过而把所有业务接口都 permitAll()。预检请求不包含业务请求的全部认证上下文,它的放行与业务接口授权是不同问题。
如果项目已有独立 CorsFilter,则需要根据过滤器顺序和实际响应验证,不要机械地同时添加以上所有示例。
九、自定义 Filter 与拦截器的注意事项
上一篇中的访问检查如果写成“所有请求都必须有令牌”,就可能误伤预检:
// 不推荐:预检通常不会带业务 Authorization,直接拒绝会阻断真正请求
if (request.getHeader("Authorization") == null) {
response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
return;
}更合理的原则是:
CORS 预检尽量由正确的 CORS 组件提前处理;
自定义 Filter 不应在 CORS 组件之前随意吞掉或拒绝
OPTIONS;MVC 拦截器如确有 OPTIONS 分支,应识别请求语义,而不是统一当业务请求鉴权;
真正的业务请求仍必须认证授权,不能靠排除
OPTIONS获得访问权限。
HandlerInterceptor 中可以先观察:
@Override
public boolean preHandle(
HttpServletRequest request,
HttpServletResponse response,
Object handler
) throws Exception {
if ("OPTIONS".equalsIgnoreCase(request.getMethod())) {
return true;
}
return checkBusinessRequest(request, response);
}是否保留这个分支取决于调用链。如果 CorsFilter 已经处理预检,它通常不会继续进入该拦截器。这里的关键不是复制代码,而是避免业务鉴权逻辑错误拦截预检。
十、按环境管理允许来源
把开发和生产来源硬编码在同一个 Java 类里,不利于部署和审计。可以通过配置属性管理。
# application.yml
app:
cors:
allowed-origins:
- http://localhost:5173生产环境通过独立配置文件或环境变量覆盖为:
app:
cors:
allowed-origins:
- https://app.example.com定义配置属性:
import java.util.List;
import org.springframework.boot.context.properties.ConfigurationProperties;
@ConfigurationProperties(prefix = "app.cors")
public record CorsProperties(List<String> allowedOrigins) {
public CorsProperties {
if (allowedOrigins == null || allowedOrigins.isEmpty()) {
throw new IllegalArgumentException("至少配置一个允许的跨域来源");
}
}
}启用并使用:
import java.util.List;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.cors.CorsConfiguration;
import org.springframework.web.cors.CorsConfigurationSource;
import org.springframework.web.cors.UrlBasedCorsConfigurationSource;
@Configuration
@EnableConfigurationProperties(CorsProperties.class)
public class CorsPropertiesConfig {
@Bean
CorsConfigurationSource corsConfigurationSource(CorsProperties properties) {
CorsConfiguration config = new CorsConfiguration();
config.setAllowedOrigins(properties.allowedOrigins());
config.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE", "OPTIONS"));
config.setAllowedHeaders(List.of("Content-Type", "Authorization"));
config.setAllowCredentials(true);
config.setMaxAge(3600L);
UrlBasedCorsConfigurationSource source =
new UrlBasedCorsConfigurationSource();
source.registerCorsConfiguration("/api/**", config);
return source;
}
}生产配置应拒绝带路径的模糊来源、拼写错误的协议和非预期端口。Origin 是协议、主机和端口的来源标识,不应填写成 https://app.example.com/api/**。
十一、响应头暴露与自定义请求头
后端返回:
X-Request-Id: 2f56f1b4f2f84a6d并不意味着跨源前端一定能通过 JavaScript 读取它。需要:
.exposedHeaders("X-Request-Id")前端才能读取被暴露的响应头:
const response = await fetch(url)
const requestId = response.headers.get('X-Request-Id')反过来,前端添加:
X-Request-Id: client-generated-id后端需要把它加入允许请求头列表,并考虑预检。不要暴露令牌、内部调试信息等不必要的响应头。
十二、预检缓存不是万能优化
.maxAge(3600)允许浏览器缓存预检结果,减少相同跨域请求前的预检次数。但具体缓存行为仍受浏览器实现和其他条件影响。
开发阶段如果修改配置后仍看到旧行为,可以:
暂时缩短
maxAge;使用新的浏览器上下文验证;
检查 Network 中实际命中的是预检还是业务请求;
确认修改的配置确实部署到了当前访问的服务与网关。
生产环境不要通过无限增大 maxAge 掩盖错误规则。预检减少不代表接口安全或性能问题已经解决。
十三、代理与网关场景只保留一个权威配置层
常见部署链路是:
浏览器 → Nginx / 网关 → Spring Boot 服务如果网关已经处理 CORS,后端服务通常不应再次追加同一组头。否则浏览器可能看到:
Access-Control-Allow-Origin: https://app.example.com, https://app.example.com这不是合法的单一允许来源值,浏览器仍会拒绝。
推荐先明确职责:
只有后端直接对外:在 Spring 应用中配置;
所有请求都经统一网关:通常由网关集中配置,后端遵循同一策略;
部分直连、部分经网关:分别核对路径,避免重叠和遗漏。
Nginx 的 add_header 还可能受继承规则、错误响应和不同 location 影响。不能只在 200 响应上验证,还应检查 4xx、5xx 和预检响应。
十四、用 curl 验证预检与真实请求
下面的命令模拟来自本地前端页面的跨源预检:
curl -i -X OPTIONS 'http://localhost:8080/api/users/1' \
-H 'Origin: http://localhost:5173' \
-H 'Access-Control-Request-Method: PUT' \
-H 'Access-Control-Request-Headers: authorization,content-type'重点检查:
HTTP 状态是否符合预期;
是否存在
Access-Control-Allow-Origin;允许来源是否与
Origin匹配;允许方法是否包含
PUT;允许请求头是否覆盖
authorization和content-type;是否出现重复 CORS 响应头。
然后验证真正的业务请求:
curl -i -X PUT 'http://localhost:8080/api/users/1' \
-H 'Origin: http://localhost:5173' \
-H 'Authorization: Bearer test-token' \
-H 'Content-Type: application/json' \
-d '{"nickname":"new-name"}'示例令牌只用于本地测试。真实请求应使用有效测试身份,并确认 401、403 等业务响应同样带有所需 CORS 头,否则前端可能只能看到笼统的网络错误。
curl 不会执行浏览器的同源策略,它只用于检查服务端响应。最终仍需在真实浏览器中验证。
十五、使用 MockMvc 验证 Spring MVC 配置
如果采用 Spring MVC 的 CORS 配置,可以增加针对预检的测试:
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.options;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.header;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.web.servlet.MockMvc;
@SpringBootTest
@AutoConfigureMockMvc
class CorsIntegrationTest {
@Autowired
MockMvc mockMvc;
@Test
void allowedOriginShouldPassPreflight() throws Exception {
mockMvc.perform(options("/api/users/1")
.header("Origin", "http://localhost:5173")
.header("Access-Control-Request-Method", "PUT")
.header("Access-Control-Request-Headers", "authorization,content-type"))
.andExpect(status().isOk())
.andExpect(header().string(
"Access-Control-Allow-Origin", "http://localhost:5173"
));
}
@Test
void disallowedOriginShouldNotReceiveAllowOrigin() throws Exception {
mockMvc.perform(options("/api/users/1")
.header("Origin", "https://untrusted.example")
.header("Access-Control-Request-Method", "PUT"))
.andExpect(header().doesNotExist("Access-Control-Allow-Origin"));
}
}测试应结合项目实际路径、方法和安全配置调整。如果项目使用独立 CorsFilter 或完整 Security 过滤器链,测试环境也必须包含对应组件,不能只测试一个孤立的 Controller。
还建议覆盖:
允许来源与不允许来源;
自定义请求头;
凭据模式;
业务请求的正常响应与 401、403 响应;
不同环境允许来源配置。
十六、跨域不是鉴权,也不能替代 CSRF 防护
只检查 Origin 并不能建立完整认证体系:
非浏览器客户端不会自动遵守 CORS;
服务器间请求可以自行构造请求头;
允许跨源读取响应不等于用户已经登录;
允许某个来源也不等于信任该来源下的所有脚本。
如果允许的来源页面发生 XSS,攻击脚本可能在用户凭据帮助下访问接口。Cookie 会话还需要根据实际请求模式设计 CSRF 防护、令牌策略和 Cookie 属性。
同样,后端之间调用、移动端请求和定时任务通常不经过浏览器 CORS 限制,必须由认证授权体系保护。
十七、常见问题自查
十八、如何选择配置方式
可以按以下顺序决策:
只有个别简单接口,且没有复杂安全链路:可以使用
@CrossOrigin。普通 Spring MVC 应用,需要统一管理多个接口:优先
WebMvcConfigurer。需要在过滤器链较早位置处理,或已有统一
CorsConfigurationSource:考虑CorsFilter。使用 Spring Security:在 Security 中启用 CORS,并复用明确的
CorsConfigurationSource。已有 API 网关集中治理:明确网关为权威配置层,避免后端重复追加。
多环境部署:把允许来源外置,按环境审查和覆盖。
选择一种主方案后,应通过预检、真实请求、错误响应和浏览器行为验证,而不是把多个示例全部叠加。
十九、总结
一套可靠的 Spring Boot 跨域方案需要同时理解浏览器和服务器:
同源策略比较协议、主机名和端口,CORS 是浏览器实施的访问控制。
简单请求与预检请求的处理过程不同,
OPTIONS不应被业务鉴权误伤。@CrossOrigin适合局部规则,全局 MVC 配置更适合集中管理。CorsFilter和 Spring Security 的 CORS 支持可以在更早的调用链处理跨域。允许来源、方法、请求头和响应头应按实际需求配置,避免无边界通配。
凭据模式不能使用任意来源思维处理,Cookie 还受 SameSite、Secure 和浏览器策略约束。
CORS 不替代认证授权、CSRF 防护或输入校验。
多层代理只应保留清晰的权威配置,避免重复响应头。
curl 适合检查响应,MockMvc 适合回归配置,最终仍需真实浏览器验证。
最佳配置不是“所有环境都复制同一段代码”,而是规则明确、来源可审计、调用链一致且有测试覆盖。
下一站预告
下一篇《Spring Boot整合MyBatis最佳实践》将进入数据访问层,介绍依赖选择、Mapper 组织、SQL 映射、分页与常见性能问题。
作者:洋洋技术笔记 发布日期:2026-11-19 系列:Spring Boot实战 - 第10篇
评论区