JavaWeb项目跨域配置详解

Java Web项目中的CORS跨域问题常被简单归咎于配置缺失，实则核心难点在于“配置生效的位置与时机”——@CrossOrigin注解仅作用于DispatcherServlet处理的Controller请求，对静态资源、Actuator端点或被Security等Filter提前拦截的请求完全无效；真正可靠的方案是采用CorsWebFilter全局配置（需正确注册、路径匹配、设置allowCredentials与具体origin而非*、合理配置maxAge），或手写Filter（务必在chain.doFilter前写入header并确保执行顺序优先于压缩等Filter）；而前端携带credentials时，后端必须显式启用凭证支持且Nginx等代理层需透传Origin和Cookie头——跨域失效往往不是代码没写对，而是请求链路中某一层悄然吞掉了CORS头。

Spring Boot 项目里用 @CrossOrigin 注解为什么有时不生效

注解只对控制器方法或类生效，但前提是请求必须进入 Spring MVC 的 DispatcherServlet 流程。静态资源、错误页、Actuator 端点、或者被其他 Filter（比如安全过滤器）提前拦截/响应的请求，@CrossOrigin 就完全不起作用。

常见错误现象：OPTIONS 预检请求返回 403 或直接 404，浏览器控制台报错 “No 'Access-Control-Allow-Origin' header”，但你的 Controller 方法明明加了 @CrossOrigin。

• 确认请求路径是否真由 @Controller 或 @RestController 处理（比如不是访问 /static/js/app.js 这类静态文件）
• 检查是否启用了 Spring Security：它默认会拦截所有预检请求，需显式放行 OPTIONS 方法
• @CrossOrigin 的 origins 值不能为 "*" 同时又设置 allowCredentials = true，否则浏览器拒绝响应

手写 CorsConfiguration + CorsWebFilter 的关键配置点

这是 Spring WebFlux 和较新 Spring Boot（2.4+）推荐的全局跨域方式，比传统 Filter 更贴合 WebMvc/WebFlux 统一模型，且能精确控制预检缓存、允许头等细节。

容易踩的坑在于：配置对象没注册进容器，或路径匹配规则写错导致部分接口漏配。

• 必须把 CorsConfiguration 包装成 CorsConfigurationSource，再传给 CorsWebFilter 构造函数
• 路径模式用 new PathPatternParser().parse("/api/**")，别用 AntPathMatcher（WebFlux 不认）
• 若需支持凭证（如 Cookie），configuration.setAllowCredentials(true) 且 origins 不能是 "*"，必须指定具体域名列表
• maxAge 设为 3600 表示预检结果缓存 1 小时，避免重复 OPTIONS 请求；设太小会加重服务端压力

自定义 Filter 实现 CORS 时 header 写入时机问题

手动在 doFilter 里 setHeader 是最直白的方式，但 header 必须在 response 提交前写入，否则会被忽略。尤其遇到异步处理、重定向、或下游 Filter 已经 flush 了 response 的情况，header 就丢了。

典型表现：GET 请求跨域正常，但 POST 或带 body 的请求失败，浏览器提示 “CORS header ‘Access-Control-Allow-Origin’ missing”。

• 务必在 chain.doFilter(request, response) 之前 设置所有 CORS header（包括 Access-Control-Allow-Origin、Access-Control-Allow-Methods 等）
• 如果项目用了 GZIP 压缩（如 TomcatServletWebServerFactory 开启了 compression），确保 CORS Filter 在压缩 Filter 之前执行（通过 @Order(Ordered.HIGHEST_PRECEDENCE)）
• 不要在 catch 块里补写 header —— 异常发生时 response 可能已提交，写入无效

前端发请求带 credentials: 'include'，后端却收不到 Cookie

这不是 CORS 配置遗漏，而是前后端协同问题：前端开了凭证，后端必须明确允许，且浏览器才会发送 Cookie；反过来，后端允许了但前端没声明，Cookie 也不会附带。

最容易被忽略的是 Nginx 或网关层二次转发时，把原始 Origin 或 Cookie 头给丢掉了。

• 后端 CorsConfiguration 或 Filter 中必须调用 setAllowCredentials(true)
• 对应地，setAllowedOrigins 不能用 "*"，得写死如 Arrays.asList("https://example.com")
• Nginx 配置里要显式透传 Origin 和 Cookie 头：proxy_set_header Origin $http_origin;、proxy_pass_request_headers on;
• 检查浏览器开发者工具 Network 标签页，看 Request Headers 是否真有 Cookie 字段 —— 没有说明前端根本没发，别急着改后端

理论要掌握，实操不能落！以上关于《JavaWeb项目跨域配置详解》的详细介绍，大家都掌握了吧！如果想要继续提升自己的能力，那么就来关注golang学习网公众号吧！