SpringBoot跨域配置：@CrossOrigin与CorsFilter详解

本文深入剖析了Spring Boot中跨域处理的两大核心机制——`@CrossOrigin`注解与`CorsFilter`（或`CorsConfigurationSource`）的原理、常见失效场景及生产级避坑指南：从注解未生效的底层原因（如误加在Service层、AOP代理干扰、WebMvcConfigurationSupport覆盖默认配置），到全局CORS配置失效的典型误区（如过滤器注册方式错误、Spring Security中未显式启用CORS），再到两者共存时的优先级逻辑与不可继承的关键配置（如`allowCredentials`），最后直击生产痛点——为何`origins = ["*"]`在现代浏览器中会彻底失败，并给出动态白名单、多域名适配及全链路排查（Nginx/CDN/浏览器版本）的实战方案，助你彻底摆脱“明明配了却仍报CORS错误”的困扰。

为什么 @CrossOrigin 加了但浏览器还是报 CORS 错误

常见现象是加了 @CrossOrigin 注解，接口能正常返回数据，但浏览器控制台仍提示 No 'Access-Control-Allow-Origin' header is present。根本原因通常是：注解没生效——比如加在了非 Controller 方法上、被 AOP 代理拦截（如 @Transactional 在同一类内调用）、或者 Spring MVC 没扫描到该类。

实操建议：

• @CrossOrigin 必须加在 @RestController 或 @Controller 标记的类或方法上，不能加在 Service 层
• 若类上已加 @CrossOrigin，方法上再加会覆盖类级配置；反之方法级优先级更高
• 检查是否启用了 WebMvcConfigurationSupport 自定义配置——它会关闭 Spring Boot 默认的 CorsConfiguration 自动注册，导致注解失效
• 确认请求路径与注解指定的 origins 完全匹配（"*" 不支持带凭证的请求，需显式写域名）

全局配置 CorsFilter 时，addMapping("/**") 为什么没生效

典型错误是把 CorsConfigurationSource bean 和 CorsFilter bean 混用，或在 WebSecurityConfigurerAdapter 中错误地禁用了 CORS（如调用了 http.cors().disable()）。

实操建议：

• Spring Boot 2.4+ 推荐用 @Bean 返回 CorsConfigurationSource，而非手动 new CorsFilter；后者容易绕过 Spring Security 的过滤链顺序
• addMapping("/**") 要配在 UrlBasedCorsConfigurationSource 上，且必须在 WebMvcConfigurer 的 addCorsMappings 方法里注册，否则只是个未挂载的配置对象
• 如果同时用了 Spring Security，必须显式启用 CORS：http.cors(Customizer.withDefaults())，否则 Security 过滤器会提前拒绝预检请求（OPTIONS）
• 注意路径匹配逻辑：Spring MVC 的 /** 匹配所有路径，但 Spring Security 的 antMatchers 若写了 /api/**，而前端发的是 /v1/api/xxx，就可能漏匹配

@CrossOrigin 和全局配置冲突时，谁起作用

不是“谁覆盖谁”，而是两套机制在不同阶段介入：注解由 RequestMappingHandlerMapping 解析，在 DispatcherServlet 分发前注入配置；全局配置（如 WebMvcConfigurer.addCorsMappings）生成的是全局默认策略，仅对未显式标注 @CrossOrigin 的端点生效。

实操建议：

• 一个接口同时有 @CrossOrigin 和全局配置 → 注解优先，全局配置被忽略
• 全局配置中设置了 allowedOrigins = ["https://a.com"]，但某个方法加了 @CrossOrigin(origins = "*") → 该方法允许任意源，其他方法仍受全局限制
• 若全局配置里设了 allowCredentials = true，但某个 @CrossOrigin 没设，那该方法仍不允许带 cookie —— 因为 allowCredentials 无法继承，必须显式声明
• 跨域头最终由 CorsProcessor 写入响应，它只读取当前请求匹配到的唯一 CorsConfiguration，不会合并多个来源

生产环境别直接用 origins = ["*"] 的真实原因

表面上是安全策略问题，实际更关键的是：Chrome 123+ 和 Safari 17+ 已强制要求，当响应头含 Access-Control-Allow-Credentials: true 时，Access-Control-Allow-Origin 不得为 "*"，否则直接抛 CORS error，连预检都过不去。

实操建议：

• 开发期可临时用 @CrossOrigin(origins = "*")，但上线前必须替换为具体域名列表，如 ["https://app.example.com", "https://staging.example.com"]
• 若前端部署在多子域（如 a.example.com, b.example.com），不能靠通配符 "*.example.com" —— CORS 规范不支持域名通配符，只能逐个列出或后端动态解析 Origin 请求头做白名单校验
• 动态白名单示例逻辑：在 CorsConfigurationSource 中取出 request.getHeader("Origin")，判断是否在预设集合内，再构造 CorsConfiguration；注意要处理空 Origin 和恶意伪造

真正麻烦的不是配错，而是线上环境混合了 Nginx 反向代理、CDN、多个前端部署域名，以及浏览器版本碎片化——这时候光看 Spring 配置没用，得抓包确认最终响应头里到底有没有、写没写对、顺序对不对。

本篇关于《SpringBoot跨域配置：@CrossOrigin与CorsFilter详解》的介绍就到此结束啦，但是学无止境，想要了解学习更多关于文章的相关知识，请关注golang学习网公众号！