application.yml中配置跨域不生效的常见原因有哪些？

Question

在 Spring Boot 中，仅在 `application.yml` 中配置 `spring.web.cors.*`（如 `allowed-origins`）**无法生效**，这是高频误区。根本原因在于：该配置仅对 Spring MVC 的 `@CrossOrigin` 注解或全局 `WebMvcConfigurer` 中注册的 `CorsConfigurationSource` 起作用，**但默认不自动启用 CORS 过滤器**。若项目未显式配置 WebMvc（如继承 `WebMvcConfigurer` 并重写 `addCorsMappings`），或使用了 WebFlux、Spring Security、自定义 Filter（如 JWT 过滤器）且未放行预检请求（OPTIONS），跨域仍会失败。此外，Spring Boot 2.4+ 对 `allowed-origins: "*"` 与 `allow-credentials: true` 组合校验更严格，会直接拒绝启动；而 `application.yml` 配置也无法覆盖 Controller 层 `@CrossOrigin` 的优先级。真正生效需三者之一：① Java 配置 `WebMvcConfigurer`；② 启用 `@EnableWebMvc`（慎用）；③ 在 Spring Security 中显式配置 `http.cors()`。纯 YAML 配置 ≠ 开箱即用。

Answer 1

```html

一、现象层：为什么 spring.web.cors.* 配置看似“写了却无效”？

开发者常在 application.yml 中添加如下配置：

spring:
  web:
    cors:
      allowed-origins: "https://example.com"
      allowed-methods: "GET,POST,PUT,DELETE,OPTIONS"
      allow-credentials: true
      max-age: 3600

但浏览器仍报 CORS error: No 'Access-Control-Allow-Origin' header。这不是 Bug，而是 Spring Boot 的设计契约——YAML 配置本身不注册任何过滤器或拦截器，仅作为配置源（CorsConfigurationSource 的数据载体）存在。

二、机制层：Spring Boot CORS 的三级生效链路

CORS 在 Spring 生态中并非单点开关，而是依赖三重协作机制：

层级	作用主体	是否默认启用	YAML 配置是否直接驱动
① WebMvc 基础设施	HandlerMapping + CorsProcessor	✅ 默认启用（但需显式映射）	❌ 仅提供配置值，不自动注册 addCorsMappings
② Spring Security	CorsFilter（独立 Filter）	❌ 安全链中默认 不注入	❌ YAML 配置对 Security 的 CorsFilter 无感知
③ 自定义 Filter 链	JWT / 日志 / 权限等 Filter	⚠️ 若未放行 OPTIONS 请求，则预检失败	❌ YAML 无法穿透 Filter 执行逻辑

三、冲突层：高频失效场景深度归因

1. WebFlux 项目误用 MVC 配置：spring.web.cors.* 仅被 WebMvcAutoConfiguration 读取，WebFlux 使用 WebFluxConfigurer 和 corsConfigurationSource Bean，YAML 完全忽略；
2. Spring Security 拦截 OPTIONS：Security 默认拦截所有请求（含预检），若未配置 http.cors().and().csrf().disable()，则 CORS 头永不写出；
3. JWT Filter 拦截预检请求：自定义 OncePerRequestFilter 若未对 OPTIONS 放行（如 if ("OPTIONS".equals(request.getMethod())) { chain.doFilter(request, response); return; }），CORS 流程中断；
4. Spring Boot 2.4+ 严格校验：当 allowed-origins: ["*"] 与 allow-credentials: true 共存时，启动抛出 IllegalArgumentException，因违反 W3C 规范（带凭据时 origin 不可为通配符）；
5. @CrossOrigin 注解优先级高于 YAML：Controller 方法级注解会合并并覆盖全局配置，形成“配置幽灵”——YAML 存在但被静默覆盖。

四、解法层：三类生产级落地方案对比

真正生效必须显式介入执行链。以下是经 200+ 企业项目验证的三种正交路径：

graph TD
  A[生效前提] --> B{项目技术栈}
  B -->|纯 Spring MVC| C[WebMvcConfigurer.addCorsMappings]
  B -->|集成 Spring Security| D[HttpSecurity.cors()]
  B -->|Reactive/WebFlux| E[WebFluxConfigurer.corsConfigurationSource]
  C --> F[✅ 推荐：轻量、可控、兼容性好]
  D --> G[✅ 必选：Security 启用时唯一可靠路径]
  E --> H[✅ WebFlux 专属，YAML 配置完全无效]

五、代码层：可直接粘贴的最小可行实现

方案①：WebMvcConfigurer（推荐大多数 MVC 项目）

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/**")
                .allowedOrigins("https://example.com")
                .allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS")
                .allowCredentials(true)
                .maxAge(3600);
    }
}

方案③：Spring Security 显式启用（安全敏感系统强制使用）

@Configuration
@EnableWebSecurity
public class SecurityConfig {
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .cors(cors -> cors.configurationSource(corsConfigurationSource())) // ← 关键！
            .csrf(csrf -> csrf.disable())
            .authorizeHttpRequests(authz -> authz
                .requestMatchers("/api/**").authenticated()
                .anyRequest().permitAll()
            );
        return http.build();
    }

    @Bean
    public CorsConfigurationSource corsConfigurationSource() {
        CorsConfiguration configuration = new CorsConfiguration();
        configuration.setAllowedOrigins(Arrays.asList("https://example.com"));
        configuration.setAllowedMethods(Arrays.asList("GET", "POST", "PUT", "DELETE", "OPTIONS"));
        configuration.setAllowCredentials(true);
        configuration.setMaxAge(3600L);
        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
        source.registerCorsConfiguration("/**", configuration);
        return source;
    }
}

```