别再被跨域卡脖子了！手把手教你用SpringBoot配置CORS，彻底搞懂OPTIONS预检
SpringBoot CORS配置全解析：从OPTIONS预检到实战避坑指南
联调时前端突然报跨域错误，明明已经在SpringBoot中配置了CORS，为什么还会出现403？这个问题困扰过不少开发者。事实上，跨域问题远不止添加几行配置那么简单，尤其是当OPTIONS预检请求介入时，情况会变得更加复杂。本文将带你深入SpringBoot CORS配置的每一个细节，揭示那些容易被忽略的陷阱。
1. 理解CORS与OPTIONS预检机制
跨域资源共享(CORS)是现代浏览器实现的安全机制，它允许网页从不同域的服务器请求资源。但浏览器在执行跨域请求前，会先进行一系列安全检查，这就是OPTIONS预检请求的由来。
简单请求与非简单请求的区别：
- 简单请求必须同时满足：
- 方法为GET、HEAD或POST
- 仅包含以下头部：Accept、Accept-Language、Content-Language、Content-Type
- Content-Type值为：application/x-www-form-urlencoded、multipart/form-data或text/plain
# 简单请求示例 GET /api/data HTTP/1.1 Host: example.com Accept: application/json- 非简单请求会触发预检：
- 使用PUT、DELETE、PATCH等方法
- 包含自定义头部
- Content-Type为application/json等非简单类型
# 非简单请求示例 POST /api/users HTTP/1.1 Host: example.com Content-Type: application/json X-Custom-Header: value提示：即使配置了CORS，如果OPTIONS预检失败，实际请求也不会发出。这是许多开发者困惑的根源。
2. SpringBoot CORS配置的深度解析
SpringBoot提供了多种CORS配置方式，但最灵活的是通过CorsFilter。下面是一个生产级配置示例：
@Configuration public class CorsConfig { @Bean public CorsFilter corsFilter() { CorsConfiguration config = new CorsConfiguration(); // 允许的源，生产环境应替换为具体域名 config.setAllowedOrigins(Arrays.asList("https://yourdomain.com")); // 是否允许凭证（cookies等） config.setAllowCredentials(true); // 允许的方法，*会包含OPTIONS config.setAllowedMethods(Arrays.asList("GET", "POST", "PUT", "DELETE")); // 允许的头部 config.setAllowedHeaders(Arrays.asList("*")); // 预检请求缓存时间（秒） config.setMaxAge(3600L); // 暴露给前端的响应头 config.setExposedHeaders(Arrays.asList("X-Custom-Header")); UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource(); source.registerCorsConfiguration("/**", config); return new CorsFilter(source); } }关键配置项解析：
| 配置项 | 作用 | 默认值 | 注意事项 |
|---|---|---|---|
| allowedOrigins | 允许的源列表 | 无 | 生产环境避免使用"*" |
| allowCredentials | 是否允许凭证 | false | 与前端withCredentials需匹配 |
| allowedMethods | 允许的HTTP方法 | GET,HEAD | 包含OPTIONS |
| maxAge | 预检结果缓存时间 | 无 | 单位秒，影响性能 |
| exposedHeaders | 暴露给JS的响应头 | 无 | 默认只能访问简单响应头 |
3. 常见问题与解决方案
3.1 OPTIONS请求返回403
这是最常见的坑点之一。即使你配置了允许POST方法，如果OPTIONS请求被拦截，仍然会失败。这是因为：
- Spring Security等安全框架可能拦截OPTIONS请求
- 自定义过滤器未正确处理OPTIONS方法
- 方法配置不完整
解决方案：
// 在Spring Security配置中添加 http.cors().and().authorizeRequests() .antMatchers(HttpMethod.OPTIONS, "/**").permitAll();3.2 凭证与跨域的矛盾
当allowCredentials为true时，allowedOrigins不能使用"*"。这是浏览器安全策略的限制。
// 错误配置 config.setAllowCredentials(true); config.addAllowedOrigin("*"); // 这将导致错误 // 正确做法 config.setAllowCredentials(true); config.setAllowedOrigins(Arrays.asList("https://yourdomain.com"));3.3 预检缓存失效
maxAge设置不当会导致浏览器频繁发送OPTIONS请求，影响性能。建议根据应用特点设置合理值：
// 设置1小时缓存 config.setMaxAge(3600L);4. 高级配置技巧
4.1 动态源配置
生产环境中，可能需要根据请求动态判断是否允许跨域：
config.setAllowedOriginPatterns(Arrays.asList("https://*.yourdomain.com"));4.2 方法级细粒度控制
对于RESTful API，可以针对不同路径设置不同的CORS规则：
UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource(); // API路径特殊配置 CorsConfiguration apiConfig = new CorsConfiguration(); apiConfig.addAllowedMethod("PUT"); apiConfig.addAllowedMethod("DELETE"); source.registerCorsConfiguration("/api/**", apiConfig); // 其他路径默认配置 source.registerCorsConfiguration("/**", config);4.3 监控与调试
添加日志帮助排查问题：
@Bean public FilterRegistrationBean<CorsFilter> corsFilterRegistration() { FilterRegistrationBean<CorsFilter> registration = new FilterRegistrationBean<>(); registration.setFilter(corsFilter()); registration.addUrlPatterns("/*"); registration.setName("corsFilter"); registration.setOrder(Ordered.HIGHEST_PRECEDENCE); return registration; }在实际项目中，我发现最容易被忽视的是exposedHeaders配置。当后端返回自定义头部时，如果未在此配置，前端JS将无法访问这些头部信息。