前后端分离架构下，跨域资源共享（CORS）几乎是每个 Spring Boot 项目都会遇到的问题。当浏览器发现请求目标与当前页面不同源时，会先发送 OPTIONS 预检请求确认服务器是否允许跨域，如果后端没有正确响应 Access-Control-Allow-Origin 等相关头部，请求就会被拦截。Spring Boot 提供了多种配置 CORS 的方式，从单个接口的注解到全局 WebMvcConfigurer，再到更底层的 CorsFilter，每种方式都有不同的粒度和适用场景。
方式一：@CrossOrigin 注解实现局部跨域
如果只需要对少数几个接口开放跨域访问，使用 @CrossOrigin 注解是最直接的选择。这个注解可以标注在控制器类或具体方法上，标注在类上时对该类所有接口生效，标注在方法上则只影响当前接口。它的底层逻辑是 Spring MVC 在映射处理器方法时，读取注解属性并生成对应的 CORS 响应头，不涉及额外的全局配置。
常见的属性包括 origins、methods、allowedHeaders、allowCredentials 和 maxAge。前三个分别控制允许的来源、HTTP 方法和请求头，allowCredentials 表示是否允许携带 Cookie 或 Authorization 等凭据，maxAge 则指定预检请求结果可以缓存多少秒。下面是一个典型的用法：
@RestController
@RequestMapping("/api/user")
public class UserController {
@CrossOrigin(origins = "http://localhost:3000",
methods = {RequestMethod.GET, RequestMethod.POST},
allowedHeaders = "*",
allowCredentials = "true",
maxAge = 3600)
@GetMapping("/{id}")
public User getUser(@PathVariable Long id) {
return userService.findById(id);
}
}
这种方式的优点是配置位置贴近接口，可读性强，不会影响其他不需要跨域的接口。但缺点也很明显：当跨域规则分散在多个控制器或方法上时，维护成本会上升，容易出现配置不一致导致部分接口仍被拦截的情况。而且 @CrossOrigin 不适用于 Spring Security 过滤链中提前拦截的场景，注解的 CORS 处理发生在 Spring MVC 的处理器映射阶段，如果请求在到达 MVC 之前就被 Security 过滤器拒绝，注解无法生效。
方式二：通过 WebMvcConfigurer 全局配置 CORS
大多数项目希望统一管理跨域规则，而不是在每个控制器上重复配置。此时可以实现 WebMvcConfigurer 接口并重写 addCorsMappings 方法，通过 CorsRegistry 注册全局 CORS 映射。Spring Boot 启动时会自动加载该配置，对所有匹配路径的请求生效。
下面的配置允许 /api/** 路径下的所有接口跨域访问，同时限制来源为 http://localhost:3000 和 https://app.ipipp.com，方法包括 GET、POST、PUT、DELETE，并开启凭据支持：
@Configuration
public class WebConfig implements WebMvcConfigurer {
@Override
public void addCorsMappings(CorsRegistry registry) {
registry.addMapping("/api/**")
.allowedOrigins("http://localhost:3000", "https://app.ipipp.com")
.allowedMethods("GET", "POST", "PUT", "DELETE")
.allowedHeaders("*")
.allowCredentials(true)
.maxAge(3600);
}
}
相比注解方式，全局注册更适合前后端分离项目中 API 前缀统一的场景。但需要特别注意两个限制。第一，当 allowCredentials(true) 时，allowedOrigins 不能设置为 *，否则浏览器会判定凭证请求的响应无效，这是 CORS 规范的限制。第二，如果要实现真正的全局放行，需要明确写出来源列表，不能为了省事把来源写成通配符又开启凭证。若确实想对所有来源开放且不携带凭证，可以使用 allowedOriginPatterns("*") 替代 allowedOrigins("*")，Spring 5.3 之后支持该写法。
另外，addMapping 的顺序不会影响匹配结果，因为 CORS 处理基于路径模式匹配，不会像安全过滤器链一样存在顺序覆盖问题。不过如果同时使用了 @CrossOrigin 和全局配置，Spring MVC 会合并两者的规则，取最宽泛的限制，而不是覆盖，这一点在排查时容易误解。
方式三：使用 CorsFilter 从过滤器层处理跨域
在 Spring Security 或其他过滤器需要提前介入的场景中，仅靠 MVC 层面的配置往往不够。例如 Spring Security 默认会对未认证的请求返回 401，而浏览器发送的预检 OPTIONS 请求通常不携带认证信息，如果安全过滤器先拦截了 OPTIONS，跨域预检就会失败。此时可以将 CORS 配置下沉到过滤器层，通过注册 CorsFilter 让它在 Spring Security 过滤器链之前执行。
Spring Boot 提供了两种创建 CorsFilter 的方式。一种是基于 CorsConfigurationSource 构建：
@Bean
public CorsFilter corsFilter() {
CorsConfiguration config = new CorsConfiguration();
config.addAllowedOrigin("http://localhost:3000");
config.addAllowedMethod("*");
config.addAllowedHeader("*");
config.setAllowCredentials(true);
config.setMaxAge(3600L);
UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
source.registerCorsConfiguration("/**", config);
return new CorsFilter(source);
}
另一种是直接使用 org.springframework.web.cors.CorsConfiguration 配合 UrlBasedCorsConfigurationSource，两者本质相同。过滤器方式会在请求进入 DispatcherServlet 之前就写入 CORS 响应头，因此对静态资源、Spring Security 过滤链以及 MVC 处理器统一生效。它的执行优先级高于 WebMvcConfigurer 和注解，适合需要全局兜底的架构。
使用 CorsFilter 时同样要注意凭证与来源的匹配关系。如果设置了 allowCredentials(true)，必须为 addAllowedOrigin 指定具体的来源，不能用 *。此外，CorsFilter 一旦注册，它会处理所有匹配路径，包括不存在的接口，这可能会导致对任意 OPTIONS 请求都返回 CORS 头部。虽然通常无害，但建议按需配置映射路径，避免暴露过宽的跨域策略。
预检请求与常见调试问题
理解了三种配置方式后，还需要掌握预检请求的机制才能快速定位问题。当一个请求使用了非简单方法（如 PUT、DELETE）或自定义请求头时，浏览器会先发送 OPTIONS 请求询问服务器允许哪些方法和头。如果服务器没有正确响应，真正的请求根本不会发出，控制台会显示类似“blocked by CORS policy”的错误。Spring Boot 的 CORS 处理器会自动响应 OPTIONS 预检，但前提是配置被正确加载。
一个常见的问题是前端使用了 Content-Type: application/json，这会触发预检，因为该 Content-Type 不属于简单请求的三种类型之一。另一个常见问题是携带 Cookie 时后端返回了 Access-Control-Allow-Credentials: true，但 Access-Control-Allow-Origin 却为 *，浏览器会拒绝。排查时可以在过滤器或拦截器中打印请求的 Origin 和 Method，对照响应头确认是否一致。
还有一个容易忽略的细节是缓存。通过 maxAge 设置预检结果缓存后，浏览器在一段时间内不会重复发送 OPTIONS 请求，此时修改后端 CORS 配置可能不会立即生效。调试阶段可以设置 maxAge 为 0 或使用浏览器无痕模式，避免缓存干扰判断。
综合来看，局部注解适合快速验证、全局 WebMvcConfigurer 适合标准前后端分离项目、CorsFilter 则用于需要与 Spring Security 协同的复杂场景。无论选择哪种方式，都要守住两条底线：开启凭证时来源必须明确，预检响应头必须由同一套 CORS 处理器生成，避免多套配置互相覆盖。
Spring BootCORS跨域配置修改时间：2026-09-25 15:17:57