Spring Boot项目里，用这3种方法配置CORS解决跨域问题（含源码分析）

Spring Boot项目中三种CORS配置方案的深度实践指南

最近在技术社区看到一个有趣的讨论：一位开发者按照网上教程前后端都配置了CORS头信息，结果跨域请求依然失败。而当他删掉前端手动添加的Access-Control-Allow-Origin头后，问题反而解决了。这个案例揭示了CORS配置中的常见误区——不是配置越多越好，关键在于理解浏览器同源策略的工作机制和Spring Boot的CORS处理流程。

1. 理解CORS的核心机制

跨源资源共享(CORS)是现代浏览器实现的安全策略，它允许服务器声明哪些外部源可以访问自己的资源。当你的Vue应用尝试从localhost:8080访问运行在localhost:8081的Spring Boot API时，浏览器会强制执行CORS检查。

**预检请求(Preflight)**是CORS中最容易引起困惑的环节。当请求满足以下任一条件时，浏览器会自动发起OPTIONS方法的预检请求：

• 使用PUT、DELETE等非简单方法
• 设置了自定义请求头（如Authorization）
• Content-Type不是application/x-www-form-urlencoded、multipart/form-data或text/plain

OPTIONS /api/resource HTTP/1.1 Host: api.example.com Origin: https://your-app.com Access-Control-Request-Method: POST Access-Control-Request-Headers: Content-Type,Authorization

服务器必须正确响应这个预检请求，浏览器才会继续发送实际请求。这就是为什么文章开头案例中，前端手动设置CORS头反而导致失败——这些响应头应该由后端返回，而不是前端发送。

2. 方法级配置：@CrossOrigin注解

对于只需要开放特定API的场景，@CrossOrigin注解是最轻量级的解决方案。这个注解可以用在控制器类或方法级别，支持细粒度的CORS策略配置。

@RestController @RequestMapping("/api/products") @CrossOrigin(origins = "https://your-frontend.com", allowedHeaders = {"Content-Type", "Authorization"}, methods = {RequestMethod.GET, RequestMethod.POST}, allowCredentials = "true") public class ProductController { @GetMapping public List<Product> listProducts() { // ... } @CrossOrigin(origins = "https://special-client.com") // 覆盖类级别配置 @PostMapping public Product createProduct(@RequestBody Product product) { // ... } }

实现原理：Spring MVC在处理方法调用时，会通过AbstractHandlerMethodMapping检查方法上的@CrossOrigin注解。当检测到跨域请求时，CorsInterceptor会拦截响应并添加相应的CORS头。

适用场景：

• 需要为不同API设置不同CORS策略
• 临时开放某些API供外部测试
• 微服务架构中特定服务的暴露

注意：当使用allowCredentials = "true"时，origins不能设为*，必须明确指定域名。这是浏览器安全策略的要求。

3. 全局配置：WebMvcConfigurer

对于大多数项目，全局统一的CORS配置是更可取的方案。Spring Boot提供了WebMvcConfigurer接口，可以集中管理CORS策略。

@Configuration public class WebConfig implements WebMvcConfigurer { @Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping("/api/**") .allowedOrigins("https://your-frontend.com", "https://staging.your-frontend.com") .allowedMethods("GET", "POST", "PUT", "DELETE") .allowedHeaders("*") .allowCredentials(true) .maxAge(3600); registry.addMapping("/public/**") .allowedOrigins("*") .allowedMethods("GET"); } }

配置项对比：

源码分析：这个配置会创建一个CorsConfiguration对象并注册到HandlerMapping。当请求到达时，CorsProcessor实现类（默认是DefaultCorsProcessor）会：

1. 检查请求是否同源
2. 判断是否为预检请求
3. 验证Origin、Method和Headers是否被允许
4. 添加相应的CORS响应头

最佳实践：

• 生产环境应该明确列出允许的域名，避免使用*
• 对于公开API，可以放宽限制但建议设置合理的maxAge
• 开发环境可以临时允许所有源，但记得在部署前修正

4. 高级控制：CorsFilter方案

当需要与Spring Security集成或实现动态CORS策略时，CorsFilter提供了最大的灵活性。这个方案在Servlet过滤器层面处理CORS，优先级最高。

@Bean public CorsFilter corsFilter() { UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource(); CorsConfiguration config = new CorsConfiguration(); // 常规配置 config.setAllowCredentials(true); config.addAllowedOrigin("https://your-frontend.com"); config.addAllowedMethod("*"); config.addAllowedHeader("*"); config.setMaxAge(3600L); // 特殊路径配置 CorsConfiguration adminConfig = new CorsConfiguration(); adminConfig.setAllowCredentials(true); adminConfig.addAllowedOrigin("https://admin.your-frontend.com"); adminConfig.addAllowedMethod("GET"); source.registerCorsConfiguration("/api/**", config); source.registerCorsConfiguration("/admin/**", adminConfig); return new CorsFilter(source); }

与Spring Security集成的关键点：

@Configuration @EnableWebSecurity public class SecurityConfig extends WebSecurityConfigurerAdapter { @Override protected void configure(HttpSecurity http) throws Exception { http.cors().and() // 启用CORS支持 .csrf().disable() // 通常API服务会禁用CSRF .authorizeRequests() .antMatchers("/api/public/**").permitAll() .anyRequest().authenticated() .and() .addFilterBefore(new CustomFilter(), UsernamePasswordAuthenticationFilter.class); } @Bean public CorsConfigurationSource corsConfigurationSource() { // 返回自定义的CorsConfigurationSource } }

动态CORS策略示例：

public class DynamicCorsConfigurationSource implements CorsConfigurationSource { private final TenantService tenantService; @Override public CorsConfiguration getCorsConfiguration(HttpServletRequest request) { String origin = request.getHeader("Origin"); if (origin == null) return null; // 根据请求参数或数据库查询动态决定是否允许 if (tenantService.isAllowedOrigin(origin)) { CorsConfiguration config = new CorsConfiguration(); config.addAllowedOrigin(origin); config.addAllowedMethod("*"); return config; } return null; } }

5. 常见问题排查指南

即使正确配置了CORS，仍然可能遇到各种边界情况。以下是几个典型问题及其解决方案：

问题1：预检请求返回403

• 现象：OPTIONS请求被拒绝
• 原因：Spring Security或其它过滤器拦截了OPTIONS方法
• 解决：确保安全配置中允许OPTIONS方法

http.authorizeRequests() .antMatchers(HttpMethod.OPTIONS).permitAll();

问题2：带Cookie的请求失败

• 现象：控制台显示Credentials flag is true, but the 'Access-Control-Allow-Credentials' header is ''
• 检查项：
  1. 后端allowCredentials(true)
  2. 前端withCredentials: true
  3. 不允许使用*作为origin

问题3：特定头信息被拦截

• 现象：自定义头如X-Requested-With无法通过
• 解决：明确添加这些头到allowedHeaders

调试技巧：

1. 使用浏览器开发者工具检查网络请求：
   • 确认预检请求和实际请求的发送顺序
   • 检查响应头是否包含预期的CORS头
2. 启用Spring Boot调试日志：

   logging.level.org.springframework.web=DEBUG logging.level.org.springframework.security=DEBUG

3. 使用CURL模拟预检请求：

   curl -X OPTIONS -H "Origin: http://your-frontend.com" \ -H "Access-Control-Request-Method: POST" \ -H "Access-Control-Request-Headers: content-type" \ http://your-api.com/endpoint -v

在最近的一个电商平台项目中，我们遇到了一个有趣的案例：在Chrome中CORS工作正常，但在某些iOS设备上的Safari中失败。最终发现是因为Safari对缓存预检响应有特殊处理，通过将maxAge设置为较短时间并确保Vary头包含Origin解决了问题。