1. 跨域问题本质解析跨域问题本质上是浏览器出于安全考虑实施的同源策略限制。当我们在前后端分离架构中开发时前端项目运行在http://localhost:3000后端API服务运行在http://localhost:8080这就构成了典型的跨域场景。浏览器会阻止这种跨域请求除非服务器明确告知浏览器允许该请求。同源策略要求协议、域名、端口三者完全相同。举个例子http://a.com 和 https://a.com 协议不同http://a.com 和 http://b.com 域名不同http://a.com:80 和 http://a.com:8080 端口不同这些情况都会触发跨域限制。在SpringBoot项目中我们最常遇到的是开发时前端服务端口与后端API端口不同导致的跨域问题。2. SpringBoot后端解决方案2.1 全局CORS配置最推荐的方式是通过配置类实现全局跨域支持Configuration public class CorsConfig implements WebMvcConfigurer { Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping(/**) .allowedOrigins(*) .allowedMethods(GET, POST, PUT, DELETE, OPTIONS) .allowedHeaders(*) .allowCredentials(true) .maxAge(3600); } }关键参数说明allowedOrigins(*)允许所有源生产环境应替换为具体的前端地址allowCredentials(true)允许携带cookie等凭证maxAge(3600)预检请求缓存时间秒2.2 控制器层注解配置对于需要精细控制的场景可以使用CrossOrigin注解RestController RequestMapping(/api) CrossOrigin(origins http://localhost:3000, allowedHeaders *, methods {RequestMethod.GET, RequestMethod.POST}) public class ApiController { // 控制器方法 }2.3 过滤器方案通过自定义过滤器实现跨域支持Component public class CorsFilter implements Filter { Override public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain) throws IOException, ServletException { HttpServletResponse response (HttpServletResponse) res; response.setHeader(Access-Control-Allow-Origin, *); response.setHeader(Access-Control-Allow-Methods, POST, GET, OPTIONS, DELETE); response.setHeader(Access-Control-Max-Age, 3600); response.setHeader(Access-Control-Allow-Headers, x-requested-with, Content-Type); chain.doFilter(req, res); } }3. 前端解决方案3.1 开发环境代理配置在Vue/React项目中配置开发服务器代理// vue.config.js module.exports { devServer: { proxy: { /api: { target: http://localhost:8080, changeOrigin: true, pathRewrite: { ^/api: } } } } }3.2 生产环境Nginx配置server { listen 80; server_name yourdomain.com; location /api { proxy_pass http://backend:8080; add_header Access-Control-Allow-Origin $http_origin; add_header Access-Control-Allow-Credentials true; add_header Access-Control-Allow-Methods GET, POST, OPTIONS; add_header Access-Control-Allow-Headers DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range; } location / { root /usr/share/nginx/html; try_files $uri $uri/ /index.html; } }4. 认证与Cookie处理当需要跨域携带Cookie时需要特殊处理后端配置registry.addMapping(/**) .allowedOrigins(http://frontend-domain.com) .allowedMethods(*) .allowCredentials(true);前端axios配置axios.defaults.withCredentials true;5. 常见问题排查5.1 OPTIONS预检请求失败现象控制台报错Request header field authorization is not allowed解决方案// SpringBoot配置中需要显式允许Authorization头 .allowedHeaders(authorization, content-type, x-requested-with)5.2 带Cookie请求被拒绝现象设置了withCredentials但Cookie未发送解决方案检查Access-Control-Allow-Origin不能为*确保Access-Control-Allow-Credentials为true前端请求配置withCredentials: true5.3 响应头未生效现象配置了CORS但浏览器仍然报跨域错误解决方案检查过滤器顺序确保CORS过滤器在安全过滤器之前清除浏览器缓存强制刷新使用Postman测试确认是浏览器限制还是服务端问题6. 安全最佳实践生产环境不要使用allowedOrigins(*)应明确指定前端域名对于敏感接口应限制允许的HTTP方法定期审查CORS配置移除不必要的宽松设置结合CSRF保护机制使用对于内部API考虑使用网关统一处理CORS7. 高级场景处理7.1 多环境配置管理通过profile区分不同环境的CORS配置# application-dev.yml cors: allowed-origins: http://localhost:3000 allowed-methods: * # application-prod.yml cors: allowed-origins: https://production.com allowed-methods: GET,POST7.2 动态源配置当需要支持多个不确定的源时Value(${cors.allowed-origins}) private String[] allowedOrigins; registry.addMapping(/**) .allowedOrigins(allowedOrigins) // 其他配置...7.3 网关层统一处理在Spring Cloud Gateway中的配置示例spring: cloud: gateway: globalcors: cors-configurations: [/**]: allowedOrigins: https://example.com allowedMethods: * allowedHeaders: * allowCredentials: true8. 测试与验证使用curl命令测试CORS配置# 测试OPTIONS预检请求 curl -X OPTIONS -H Origin: http://test.com \ -H Access-Control-Request-Method: POST \ -H Access-Control-Request-Headers: content-type \ -v http://api.example.com/endpoint # 测试实际请求 curl -X POST -H Origin: http://test.com \ -H Content-Type: application/json \ -d {key:value} \ -v http://api.example.com/endpoint验证响应头中应包含Access-Control-Allow-OriginAccess-Control-Allow-MethodsAccess-Control-Allow-Headers9. 性能优化建议合理设置maxAge减少OPTIONS请求对于静态资源使用CDN并配置CORS避免在过滤器链中重复处理CORS对于高频接口考虑缓存CORS响应10. 版本兼容性说明不同SpringBoot版本CORS处理差异SpringBoot版本特点2.4.x之前WebMvcConfigurer方式兼容性好2.4.x之后新增CorsRegistration配置选项3.0.x对CORS处理有优化性能更好11. 替代方案比较方案优点缺点适用场景注解配置细粒度控制重复配置特定接口特殊需求全局配置统一管理不够灵活大多数通用场景过滤器最早介入需要手动处理需要最低层控制网关层统一入口额外组件微服务架构12. 实际案例分享某电商平台前后端分离架构中的CORS配置演进初期开发阶段.allowedOrigins(*) .allowedMethods(*)上线前调整为.allowedOrigins(https://www.eshop.com, https://m.eshop.com) .allowedMethods(GET, POST, PUT) .allowCredentials(true)遇到第三方支付回调问题后// 支付回调特殊处理 registry.addMapping(/api/pay/callback) .allowedOrigins(*) .allowedMethods(POST);13. 调试技巧Chrome开发者工具中重点关注Network标签中的请求头Origin和响应头Access-Control-*Console中的CORS错误信息Application Cookies查看跨域Cookie情况关键调试命令// 查看实际发送的请求头 console.log(Request headers:, new Headers(request.headers))14. 浏览器兼容性各浏览器对CORS的实现差异浏览器特殊行为解决方案Chrome严格模式限制多确保响应头完整Safari对credentials要求严明确设置credentialsFirefox缓存行为不同适当降低maxAgeEdge错误信息不同多浏览器测试15. 扩展思考当遇到更复杂的跨域场景时WebSocket跨域registry.addMapping(/ws/**) .allowedOrigins(https://example.com) .allowedMethods(*)文件上传跨域需要额外暴露Content-Disposition头可能需要配置multipart特殊处理SSE(Server-Sent Events).addExposedHeader(Content-Type, text/event-stream) SpringBoot跨域解决方案与CORS配置详解
1. 跨域问题本质解析跨域问题本质上是浏览器出于安全考虑实施的同源策略限制。当我们在前后端分离架构中开发时前端项目运行在http://localhost:3000后端API服务运行在http://localhost:8080这就构成了典型的跨域场景。浏览器会阻止这种跨域请求除非服务器明确告知浏览器允许该请求。同源策略要求协议、域名、端口三者完全相同。举个例子http://a.com 和 https://a.com 协议不同http://a.com 和 http://b.com 域名不同http://a.com:80 和 http://a.com:8080 端口不同这些情况都会触发跨域限制。在SpringBoot项目中我们最常遇到的是开发时前端服务端口与后端API端口不同导致的跨域问题。2. SpringBoot后端解决方案2.1 全局CORS配置最推荐的方式是通过配置类实现全局跨域支持Configuration public class CorsConfig implements WebMvcConfigurer { Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping(/**) .allowedOrigins(*) .allowedMethods(GET, POST, PUT, DELETE, OPTIONS) .allowedHeaders(*) .allowCredentials(true) .maxAge(3600); } }关键参数说明allowedOrigins(*)允许所有源生产环境应替换为具体的前端地址allowCredentials(true)允许携带cookie等凭证maxAge(3600)预检请求缓存时间秒2.2 控制器层注解配置对于需要精细控制的场景可以使用CrossOrigin注解RestController RequestMapping(/api) CrossOrigin(origins http://localhost:3000, allowedHeaders *, methods {RequestMethod.GET, RequestMethod.POST}) public class ApiController { // 控制器方法 }2.3 过滤器方案通过自定义过滤器实现跨域支持Component public class CorsFilter implements Filter { Override public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain) throws IOException, ServletException { HttpServletResponse response (HttpServletResponse) res; response.setHeader(Access-Control-Allow-Origin, *); response.setHeader(Access-Control-Allow-Methods, POST, GET, OPTIONS, DELETE); response.setHeader(Access-Control-Max-Age, 3600); response.setHeader(Access-Control-Allow-Headers, x-requested-with, Content-Type); chain.doFilter(req, res); } }3. 前端解决方案3.1 开发环境代理配置在Vue/React项目中配置开发服务器代理// vue.config.js module.exports { devServer: { proxy: { /api: { target: http://localhost:8080, changeOrigin: true, pathRewrite: { ^/api: } } } } }3.2 生产环境Nginx配置server { listen 80; server_name yourdomain.com; location /api { proxy_pass http://backend:8080; add_header Access-Control-Allow-Origin $http_origin; add_header Access-Control-Allow-Credentials true; add_header Access-Control-Allow-Methods GET, POST, OPTIONS; add_header Access-Control-Allow-Headers DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range; } location / { root /usr/share/nginx/html; try_files $uri $uri/ /index.html; } }4. 认证与Cookie处理当需要跨域携带Cookie时需要特殊处理后端配置registry.addMapping(/**) .allowedOrigins(http://frontend-domain.com) .allowedMethods(*) .allowCredentials(true);前端axios配置axios.defaults.withCredentials true;5. 常见问题排查5.1 OPTIONS预检请求失败现象控制台报错Request header field authorization is not allowed解决方案// SpringBoot配置中需要显式允许Authorization头 .allowedHeaders(authorization, content-type, x-requested-with)5.2 带Cookie请求被拒绝现象设置了withCredentials但Cookie未发送解决方案检查Access-Control-Allow-Origin不能为*确保Access-Control-Allow-Credentials为true前端请求配置withCredentials: true5.3 响应头未生效现象配置了CORS但浏览器仍然报跨域错误解决方案检查过滤器顺序确保CORS过滤器在安全过滤器之前清除浏览器缓存强制刷新使用Postman测试确认是浏览器限制还是服务端问题6. 安全最佳实践生产环境不要使用allowedOrigins(*)应明确指定前端域名对于敏感接口应限制允许的HTTP方法定期审查CORS配置移除不必要的宽松设置结合CSRF保护机制使用对于内部API考虑使用网关统一处理CORS7. 高级场景处理7.1 多环境配置管理通过profile区分不同环境的CORS配置# application-dev.yml cors: allowed-origins: http://localhost:3000 allowed-methods: * # application-prod.yml cors: allowed-origins: https://production.com allowed-methods: GET,POST7.2 动态源配置当需要支持多个不确定的源时Value(${cors.allowed-origins}) private String[] allowedOrigins; registry.addMapping(/**) .allowedOrigins(allowedOrigins) // 其他配置...7.3 网关层统一处理在Spring Cloud Gateway中的配置示例spring: cloud: gateway: globalcors: cors-configurations: [/**]: allowedOrigins: https://example.com allowedMethods: * allowedHeaders: * allowCredentials: true8. 测试与验证使用curl命令测试CORS配置# 测试OPTIONS预检请求 curl -X OPTIONS -H Origin: http://test.com \ -H Access-Control-Request-Method: POST \ -H Access-Control-Request-Headers: content-type \ -v http://api.example.com/endpoint # 测试实际请求 curl -X POST -H Origin: http://test.com \ -H Content-Type: application/json \ -d {key:value} \ -v http://api.example.com/endpoint验证响应头中应包含Access-Control-Allow-OriginAccess-Control-Allow-MethodsAccess-Control-Allow-Headers9. 性能优化建议合理设置maxAge减少OPTIONS请求对于静态资源使用CDN并配置CORS避免在过滤器链中重复处理CORS对于高频接口考虑缓存CORS响应10. 版本兼容性说明不同SpringBoot版本CORS处理差异SpringBoot版本特点2.4.x之前WebMvcConfigurer方式兼容性好2.4.x之后新增CorsRegistration配置选项3.0.x对CORS处理有优化性能更好11. 替代方案比较方案优点缺点适用场景注解配置细粒度控制重复配置特定接口特殊需求全局配置统一管理不够灵活大多数通用场景过滤器最早介入需要手动处理需要最低层控制网关层统一入口额外组件微服务架构12. 实际案例分享某电商平台前后端分离架构中的CORS配置演进初期开发阶段.allowedOrigins(*) .allowedMethods(*)上线前调整为.allowedOrigins(https://www.eshop.com, https://m.eshop.com) .allowedMethods(GET, POST, PUT) .allowCredentials(true)遇到第三方支付回调问题后// 支付回调特殊处理 registry.addMapping(/api/pay/callback) .allowedOrigins(*) .allowedMethods(POST);13. 调试技巧Chrome开发者工具中重点关注Network标签中的请求头Origin和响应头Access-Control-*Console中的CORS错误信息Application Cookies查看跨域Cookie情况关键调试命令// 查看实际发送的请求头 console.log(Request headers:, new Headers(request.headers))14. 浏览器兼容性各浏览器对CORS的实现差异浏览器特殊行为解决方案Chrome严格模式限制多确保响应头完整Safari对credentials要求严明确设置credentialsFirefox缓存行为不同适当降低maxAgeEdge错误信息不同多浏览器测试15. 扩展思考当遇到更复杂的跨域场景时WebSocket跨域registry.addMapping(/ws/**) .allowedOrigins(https://example.com) .allowedMethods(*)文件上传跨域需要额外暴露Content-Disposition头可能需要配置multipart特殊处理SSE(Server-Sent Events).addExposedHeader(Content-Type, text/event-stream)