springboot 跨域配置（超详细）

💡一则或许对你有用的小广告

欢迎加入小哈的星球 ，你将获得：专属的项目实战(已更新的所有项目都能学习) / 1v1 提问 / Java 学习路线 / 学习打卡 / 每月赠书 / 社群讨论

• 新开坑项目:《Spring AI 项目实战》 正在持续爆肝中，基于 Spring AI + Spring Boot 3.x + JDK 21...， 点击查看 ;
• 《从零手撸：仿小红书（微服务架构）》 已完结，基于 Spring Cloud Alibaba + Spring Boot 3.x + JDK 17...，点击查看项目介绍 ;演示链接： http://116.62.199.48:7070 ;
• 《从零手撸：前后端分离博客项目（全栈开发）》 2 期已完结，演示链接： http://116.62.199.48/ ;

截止目前， 星球 内专栏累计输出 90w+ 字，讲解图 3441+ 张，还在持续爆肝中.. 后续还会上新更多项目，目标是将 Java 领域典型的项目都整一波，如秒杀系统, 在线商城, IM 即时通讯，权限管理，Spring Cloud Alibaba 微服务等等，已有 3100+ 小伙伴加入学习 ，欢迎点击围观

前言：理解跨域问题与 Spring Boot 的应对策略

在现代 Web 开发中，前后端分离架构逐渐成为主流。前端应用与后端 API 往往运行在不同的端口或域名下，这便引出了一个关键问题：跨域请求。当浏览器检测到请求的来源（域名、协议、端口）与当前页面的来源不一致时，便会触发同源策略（Same-Origin Policy），阻止请求的执行。

Spring Boot 作为 Java 后端的主流框架，提供了多种灵活的跨域解决方案。本文将从基础概念到实战配置，逐步解析 Spring Boot 跨域配置 的实现原理与最佳实践。无论是初学者还是有一定经验的开发者，都能通过本文掌握如何优雅地解决跨域问题。

一、同源策略与跨域问题的根源

1.1 同源策略的定义与作用

同源策略是浏览器为保障用户隐私和安全而设计的核心机制。其核心规则是：只有协议、域名、端口完全一致的请求，才被视为“同源”。例如，http://example.com:8080/api 与 http://example.com:3000/page 因端口不同，会被认定为跨域。

比喻：可以将同源策略想象为一座城市的门卫系统。门卫（浏览器）会严格检查所有试图进入的“访客”（请求），只有来自同一街区（同源）的访客才能自由通行，而外来访客需要额外的凭证（跨域配置）。

1.2 跨域请求的典型场景

以下场景常引发跨域问题：

• 前端页面运行在 http://localhost:3000，后端 API 运行在 http://localhost:8080。
• 前端通过 fetch 或 axios 发送请求至第三方服务（如天气 API）。
• 单页应用（SPA）与后端 API 部署在不同子域下（如 api.example.com 和 www.example.com）。

二、Spring Boot 跨域配置的核心方法

Spring Boot 提供了三种主流的跨域解决方案，开发者可根据项目需求灵活选择。

2.1 全局配置：通过 application.properties 禁用跨域检查

这是最简单的配置方式，但仅适用于开发环境。通过设置以下属性，可全局允许所有跨域请求：

spring.mvc.throw-exception-if-no-handler-found=true  
spring.resources.add-mappings=false  

注意：此方法直接绕过了跨域安全检查，生产环境应避免使用。

2.2 基于 @CrossOrigin 注解的局部配置

若仅需对特定接口开放跨域权限，可通过 @CrossOrigin 注解标注在 Controller 或方法上：

@RestController  
@CrossOrigin(origins = "http://localhost:3000") // 允许指定来源  
public class UserController {  
    @GetMapping("/users")  
    public List<User> getUsers() {  
        return userService.findAll();  
    }  
}  

参数详解：
| 参数 | 说明 |
|--------------|----------------------------------------------------------------------|
| origins | 允许的请求来源，支持通配符 *（生产环境慎用） |
| methods | 允许的 HTTP 方法（如 RequestMethod.GET） |
| allowedHeaders | 允许的请求头 |
| exposedHeaders | 允许前端访问的响应头 |

优势：配置灵活，可针对单个接口精细化控制。

2.3 自定义 CORS 配置：全局与动态策略

对于复杂场景（如动态域名支持），可通过实现 WebMvcConfigurer 接口进行全局配置：

@Configuration  
public class CorsConfig implements WebMvcConfigurer {  
    @Override  
    public void addCorsMappings(CorsRegistry registry) {  
        registry.addMapping("/**") // 应用到所有路径  
            .allowedOrigins("http://localhost:3000", "https://example.com")  
            .allowedMethods("GET", "POST", "PUT", "DELETE")  
            .allowCredentials(true) // 允许携带 Cookie  
            .maxAge(3600); // 预检请求缓存时间（秒）  
    }  
}  

关键点解析：

• addMapping("/**") 表示配置对所有路径生效，也可指定 /api/** 等路径模式。
• allowCredentials(true) 需与前端 withCredentials: true 配合使用，以支持跨域携带 Cookie。

三、实战案例：构建一个跨域友好的 API

3.1 场景描述

假设我们有一个前后端分离的项目：

• 后端 Spring Boot API 运行在 http://localhost:8080。
• 前端 Vue.js 应用运行在 http://localhost:3000。

3.2 分步实现

步骤 1：添加 CORS 全局配置

创建 CorsConfig 类，配置允许的来源和方法：

@Configuration  
public class CorsConfig {  
    @Bean  
    public CorsFilter corsFilter() {  
        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();  
        CorsConfiguration config = new CorsConfiguration();  
        config.addAllowedOrigin("http://localhost:3000");  
        config.addAllowedMethod("*");  
        config.addAllowedHeader("*");  
        source.registerCorsConfiguration("/**", config);  
        return new CorsFilter(source);  
    }  
}  

步骤 2：前端发起请求

在 Vue 组件中使用 axios 发送 GET 请求：

axios.get('http://localhost:8080/api/data')  
    .then(response => {  
        console.log('数据获取成功:', response.data);  
    })  
    .catch(error => {  
        console.error('跨域请求失败:', error);  
    });  

步骤 3：验证结果

若配置正确，浏览器控制台将显示成功响应，而非跨域错误。

四、常见问题与解决方案

4.1 配置生效后仍报错

可能原因：

• 浏览器缓存了旧的 CORS 响应，尝试清除缓存或使用无痕模式。
• allowedHeaders 未包含请求中实际使用的自定义头（如 Content-Type）。

解决方案：

config.addAllowedHeader("Content-Type"); // 显式添加必要头  

4.2 生产环境的安全配置建议

• 避免使用 allowedOrigins = "*" "，应明确列出可信来源。
• 禁用 allowCredentials 除非必要，并确保 Cookie 的安全性（如设置 Secure 和 HttpOnly 标志）。

五、进阶技巧：动态 CORS 配置与安全优化

5.1 基于请求动态判断来源

可通过 CorsConfigurationSource 实现动态策略：

@Bean  
public CorsConfigurationSource corsConfigurationSource() {  
    return request -> {  
        CorsConfiguration config = new CorsConfiguration();  
        String origin = request.getHeader("Origin");  
        if ("http://localhost:3000".equals(origin)) {  
            config.addAllowedOrigin(origin);  
            config.addAllowedMethod("POST");  
        }  
        return config;  
    };  
}  

5.2 结合 Spring Security 配置

若项目使用 Spring Security，需在安全配置中单独处理 CORS：

@Configuration  
@EnableWebSecurity  
public class SecurityConfig extends WebSecurityConfigurerAdapter {  
    @Override  
    protected void configure(HttpSecurity http) throws Exception {  
        http.cors().and().csrf().disable() // 禁用 CSRF 或自定义策略  
            .authorizeRequests()  
            .anyRequest().authenticated();  
    }  
}  

结论：选择适合的跨域配置策略

通过本文的讲解，开发者应能根据项目需求选择合适的 Spring Boot 跨域配置 方案：

• 简单场景：使用 @CrossOrigin 注解或全局属性快速实现。
• 复杂场景：通过自定义 CorsConfig 实现细粒度控制与动态策略。
• 生产环境：始终遵循最小权限原则，结合安全框架（如 Spring Security）保障数据安全。

跨域配置不仅是技术问题，更是架构设计的一部分。建议开发者在项目初期就规划好前后端交互协议，并通过单元测试验证配置的健壮性。掌握这些技巧后，您将能更自信地构建安全、高效的分布式系统。

关键词布局示例：

• 标题与小标题中自然嵌入“Spring Boot 跨域配置”关键词。
• 在代码示例与解决方案中提及具体配置方法，如“全局跨域配置”“动态跨域策略”。
• 结论部分总结关键词应用场景，强化读者对核心概念的记忆。