Spring Boot 全局跨域配置與前后端聯(lián)調(diào)避坑
在前后端分離開發(fā)模式中，跨域問題是聯(lián)調(diào)階段最常見、最容易卡進(jìn)度的問題之一。前面我們完成了接口開發(fā)、全局異常處理、參數(shù)校驗(yàn)、接口日志統(tǒng)一打印等基礎(chǔ)能力搭建，項(xiàng)目接口已經(jīng)具備完整的業(yè)務(wù)能力和問題排查能力。但一旦前端通過Vue、React等框架獨(dú)立部署訪問后端接口，瀏覽器就會(huì)觸發(fā)CORS跨域攔截，出現(xiàn)控制臺(tái)報(bào)跨域錯(cuò)誤、請(qǐng)求無響應(yīng)、預(yù)檢請(qǐng)求失敗、403跨域拒絕等問題，導(dǎo)致前后端完全無法聯(lián)調(diào)。
很多新手解決跨域只會(huì)簡(jiǎn)單使用注解或者配置通配符，看似臨時(shí)解決問題，卻會(huì)埋下大量線上隱患：生產(chǎn)環(huán)境跨域失效、攜帶Token請(qǐng)求報(bào)錯(cuò)、PUT/DELETE請(qǐng)求攔截、SpringSecurity沖突、多配置優(yōu)先級(jí)混亂等。本文將從跨域核心原理入手，講解企業(yè)級(jí)標(biāo)準(zhǔn)的全局跨域配置方案，對(duì)比多種配置方式的優(yōu)劣，重點(diǎn)梳理前后端聯(lián)調(diào)的高頻坑點(diǎn)與解決方案，適配Spring Boot2.x、3.x全版本，一套配置適配開發(fā)、測(cè)試、生產(chǎn)全環(huán)境，徹底根治跨域問題。
一、跨域核心原理與產(chǎn)生原因
1.1 什么是跨域
跨域全稱跨域資源共享（CORS），是瀏覽器為了防范惡意網(wǎng)站竊取數(shù)據(jù)的安全同源策略限制。瀏覽器規(guī)定：只有協(xié)議、域名、端口三者完全一致，才屬于同源請(qǐng)求，允許正常訪問接口；任意一個(gè)要素不同，即判定為跨域請(qǐng)求，瀏覽器會(huì)攔截響應(yīng)數(shù)據(jù)。
前后端分離項(xiàng)目天然存在跨域場(chǎng)景：前端本地運(yùn)行在 http://localhost:8080，后端接口運(yùn)行在 http://localhost:8088，端口不一致，直接觸發(fā)跨域攔截。需要注意的是：跨域是瀏覽器的限制，和后端服務(wù)無關(guān)，后端接口本身已經(jīng)正常執(zhí)行，只是瀏覽器拒絕接收響應(yīng)結(jié)果。
1.2 簡(jiǎn)單請(qǐng)求與預(yù)檢請(qǐng)求（核心避坑基礎(chǔ)）
瀏覽器將跨域請(qǐng)求分為兩類，不同請(qǐng)求的跨域校驗(yàn)規(guī)則完全不同，絕大多數(shù)聯(lián)調(diào)報(bào)錯(cuò)都源于對(duì)這兩種請(qǐng)求的認(rèn)知缺失：
1. 簡(jiǎn)單請(qǐng)求
僅支持 GET、POST、HEAD 三種請(qǐng)求方式，且請(qǐng)求頭僅包含基礎(chǔ)字段、無自定義請(qǐng)求頭、無復(fù)雜請(qǐng)求體。簡(jiǎn)單請(qǐng)求不會(huì)發(fā)送預(yù)檢請(qǐng)求，瀏覽器直接發(fā)起接口請(qǐng)求，通過響應(yīng)頭判斷是否允許跨域。
2. 預(yù)檢請(qǐng)求（OPTIONS請(qǐng)求）
PUT、DELETE 請(qǐng)求、攜帶 Token 自定義請(qǐng)求頭、復(fù)雜JSON請(qǐng)求體等場(chǎng)景，都會(huì)觸發(fā)預(yù)檢請(qǐng)求。瀏覽器會(huì)先發(fā)送一次 OPTIONS 預(yù)檢請(qǐng)求，詢問后端是否允許當(dāng)前跨域請(qǐng)求，預(yù)檢通過后，才會(huì)發(fā)起真正的業(yè)務(wù)請(qǐng)求。若后端未處理 OPTIONS 請(qǐng)求，會(huì)直接跨域報(bào)錯(cuò)，業(yè)務(wù)請(qǐng)求無法執(zhí)行。
同時(shí) Spring Boot 3.x 對(duì)預(yù)檢請(qǐng)求規(guī)則大幅收緊，舊版本默認(rèn)兼容所有請(qǐng)求方法，3.x 版本默認(rèn)僅允許 GET、POST、HEAD，若未手動(dòng)配置 PUT、DELETE 方法，會(huì)直接攔截請(qǐng)求，這是高版本項(xiàng)目跨域失效的核心原因之一。
二、常見跨域解決方案優(yōu)劣對(duì)比
Spring Boot 提供多種跨域解決方案，不同方案適配場(chǎng)景、優(yōu)先級(jí)、穩(wěn)定性差異極大，新手極易混用導(dǎo)致沖突。這里對(duì)四種主流方案做完整對(duì)比，幫助大家按需選擇：
2.1 @CrossOrigin 注解（局部方案，不推薦全局使用）
直接在 Controller 類或接口方法上添加注解，僅對(duì)當(dāng)前類/接口生效，優(yōu)點(diǎn)是使用簡(jiǎn)單、按需開啟，缺點(diǎn)是配置分散、無法統(tǒng)一管理、后期維護(hù)成本極高，大型項(xiàng)目不推薦使用。同時(shí)該注解和全局配置混用會(huì)出現(xiàn)優(yōu)先級(jí)混亂，導(dǎo)致跨域規(guī)則失效。
2.2 過濾器跨域配置（CorsFilter）
通過注冊(cè) CorsFilter 過濾器統(tǒng)一攔截所有請(qǐng)求，配置集中、優(yōu)先級(jí)高，適配所有版本 Spring Boot，兼容性極強(qiáng)，適合需要精細(xì)控制跨域規(guī)則、整合權(quán)限框架的項(xiàng)目。
2.3 WebMvc全局配置（最常用、企業(yè)首選）
實(shí)現(xiàn) WebMvcConfigurer 接口，重寫跨域方法，全局統(tǒng)一配置所有接口跨域規(guī)則，代碼簡(jiǎn)潔、無侵入、便于維護(hù)，是絕大多數(shù)前后端分離項(xiàng)目的標(biāo)準(zhǔn)方案，本文重點(diǎn)主推該方案。
2.4 配置文件跨域（極簡(jiǎn)，適合簡(jiǎn)單項(xiàng)目）
Spring Boot2.4+ 支持直接在 yml 配置文件配置跨域，無需編寫代碼，極簡(jiǎn)高效，但靈活性較低，無法適配復(fù)雜場(chǎng)景（多域名、動(dòng)態(tài)域名、自定義請(qǐng)求頭），僅適合小型簡(jiǎn)單項(xiàng)目。
三、企業(yè)級(jí)全局跨域配置（無導(dǎo)包、可直接落地）
本文提供兩套最穩(wěn)定的全局跨域方案，適配不同項(xiàng)目場(chǎng)景，二選一使用，禁止混用，徹底避免配置沖突問題。所有代碼均刪除導(dǎo)包語(yǔ)句，直接復(fù)制即可使用。
3.1 方案一：WebMvcConfigurer 全局跨域（推薦，通用所有場(chǎng)景）
該方案集中管理所有跨域規(guī)則，支持多域名、通配符域名、所有請(qǐng)求方法、攜帶Cookie與Token，自動(dòng)處理OPTIONS預(yù)檢請(qǐng)求，適配Spring Boot2.x、3.x全版本，是企業(yè)項(xiàng)目通用標(biāo)準(zhǔn)配置。
// 全局跨域配置類（統(tǒng)一解決前后端跨域問題）
@Configuration
public class CorsConfig implements WebMvcConfigurer {
/**
* 全局跨域規(guī)則配置
* 適配所有接口、所有前端域名、所有請(qǐng)求方式，支持Token、Cookie跨域傳遞
*/
@Override
public void addCorsMappings(CorsRegistry registry) {
registry.addMapping("/**")
// 適配多環(huán)境前端域名，支持通配符匹配
.allowedOriginPatterns("http://localhost:*", "http://127.0.0.1:*")
// 放行所有業(yè)務(wù)請(qǐng)求方法 + OPTIONS預(yù)檢請(qǐng)求
.allowedMethods("GET", "POST", "PUT", "DELETE", "OPTIONS")
// 放行所有自定義請(qǐng)求頭（適配Token、自定義參數(shù)頭）
.allowedHeaders("*")
// 允許跨域攜帶Cookie、Token憑證（核心配置）
.allowCredentials(true)
// 預(yù)檢請(qǐng)求緩存時(shí)長(zhǎng)（1小時(shí)，減少重復(fù)預(yù)檢請(qǐng)求，提升聯(lián)調(diào)效率）
.maxAge(3600);
}
}核心配置詳解：
- allowedOriginPatterns：替代舊版 allowedOrigins，支持通配符，解決固定域名無法適配多端口、多環(huán)境的問題，同時(shí)避免 allowCredentials=true 時(shí)通配符報(bào)錯(cuò)；
- allowedMethods包含OPTIONS：專門處理前端預(yù)檢請(qǐng)求，徹底解決PUT/DELETE請(qǐng)求跨域失敗問題，適配Spring Boot3.x高版本嚴(yán)格校驗(yàn)規(guī)則；
- allowCredentials=true：開啟憑證跨域，允許前端傳遞Cookie、Token、Session，是登錄認(rèn)證、權(quán)限校驗(yàn)場(chǎng)景的必備配置。
3.2 方案二：配置文件極簡(jiǎn)跨域（適合小型項(xiàng)目）
無需編寫Java代碼，僅通過yml配置文件快速開啟跨域，適配Spring Boot2.4及以上版本，簡(jiǎn)單高效，適合功能簡(jiǎn)單、無需復(fù)雜跨域規(guī)則的項(xiàng)目。
# 全局跨域配置（Spring Boot2.4+ 專屬）
spring:
web:
cors:
# 允許的前端域名（多域名用逗號(hào)分隔）
allowed-origins: http://localhost:8080,http://127.0.0.1:8080
# 允許的請(qǐng)求方法
allowed-methods: GET,POST,PUT,DELETE,OPTIONS
# 允許攜帶憑證
allow-credentials: true
# 預(yù)檢請(qǐng)求緩存時(shí)間
max-age: 3600
# 允許所有請(qǐng)求頭
allowed-headers: "*"3.3 方案三：CorsFilter 過濾器跨域（適配SpringSecurity項(xiàng)目）
若項(xiàng)目集成了SpringSecurity權(quán)限框架，普通WebMvc跨域配置會(huì)失效，必須使用過濾器方式配置跨域，否則預(yù)檢請(qǐng)求會(huì)被安全框架攔截，聯(lián)調(diào)必報(bào)錯(cuò)。
// SpringSecurity適配跨域配置
@Configuration
public class SecurityCorsConfig {
@Bean
public CorsFilter corsFilter() {
CorsConfiguration config = new CorsConfiguration();
// 允許跨域域名
config.setAllowedOriginPatterns("http://localhost:*", "http://127.0.0.1:*");
// 允許請(qǐng)求方法
config.setAllowedMethods(Arrays.asList("GET","POST","PUT","DELETE","OPTIONS"));
// 允許請(qǐng)求頭
config.setAllowedHeaders(Arrays.asList("*"));
// 允許憑證傳遞
config.setAllowCredentials(true);
// 預(yù)檢緩存時(shí)間
config.setMaxAge(3600L);
UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
source.registerCorsConfiguration("/**", config);
return new CorsFilter(source);
}
}
四、前后端聯(lián)調(diào)高頻跨域坑點(diǎn)深度避坑
大部分跨域報(bào)錯(cuò)并非配置未生效，而是配置不規(guī)范、版本不兼容、前后端參數(shù)不匹配導(dǎo)致。下面整理聯(lián)調(diào)過程中99%開發(fā)者都會(huì)遇到的坑點(diǎn)，附帶完整解決方案。
坑點(diǎn)1：allowCredentials=true 與 * 通配符沖突報(bào)錯(cuò)
報(bào)錯(cuò)現(xiàn)象：開啟憑證跨域后，使用 allowedOrigins(“*”) 全局放行域名，瀏覽器直接報(bào)跨域錯(cuò)誤，無法攜帶Token。
原因：瀏覽器安全規(guī)范禁止 允許憑證 + 任意域名 同時(shí)生效，認(rèn)為該組合存在極大安全風(fēng)險(xiǎn)，Spring Boot高版本直接攔截該配置。
解決方案：放棄 allowedOrigins 通配符，使用 allowedOriginPatterns 支持通配符匹配，完美兼容憑證跨域，也是目前官方推薦寫法。
坑點(diǎn)2：PUT/DELETE 請(qǐng)求跨域失敗，GET/POST正常
報(bào)錯(cuò)現(xiàn)象：普通查詢、新增接口正常，修改、刪除接口直接跨域，無業(yè)務(wù)日志輸出。
原因：PUT/DELETE請(qǐng)求觸發(fā)瀏覽器OPTIONS預(yù)檢請(qǐng)求，項(xiàng)目未配置放行OPTIONS方法，預(yù)檢請(qǐng)求攔截，導(dǎo)致真實(shí)請(qǐng)求無法發(fā)起；Spring Boot3.x默認(rèn)僅放行GET、POST、HEAD，未手動(dòng)配置會(huì)直接攔截。
解決方案：跨域配置中主動(dòng)添加 OPTIONS 請(qǐng)求方法，全局放行預(yù)檢請(qǐng)求。
坑點(diǎn)3：@CrossOrigin 注解與全局配置混用沖突
報(bào)錯(cuò)現(xiàn)象：部分接口跨域正常，部分接口隨機(jī)報(bào)錯(cuò)，規(guī)則混亂、難以排查。
原因：注解跨域和全局跨域配置優(yōu)先級(jí)不統(tǒng)一，相互覆蓋，導(dǎo)致跨域規(guī)則錯(cuò)亂。
解決方案：項(xiàng)目統(tǒng)一使用全局跨域配置，刪除所有接口上的@CrossOrigin注解，配置集中統(tǒng)一管理，杜絕沖突。
坑點(diǎn)4：跨域配置正常，攜帶Token后報(bào)錯(cuò)
報(bào)錯(cuò)現(xiàn)象：不帶Token的普通請(qǐng)求正常，登錄后攜帶Token請(qǐng)求直接跨域。
原因：未開啟allowCredentials憑證跨域，或未放行自定義Authorization請(qǐng)求頭，瀏覽器攔截帶憑證的跨域請(qǐng)求。
解決方案：開啟allowCredentials=true，同時(shí)通過allowedHeaders放行所有自定義請(qǐng)求頭，確保Token可以正常傳遞。
坑點(diǎn)5：開發(fā)環(huán)境正常，生產(chǎn)環(huán)境跨域失效
報(bào)錯(cuò)現(xiàn)象：本地聯(lián)調(diào)完全正常，部署服務(wù)器后前端頁(yè)面跨域報(bào)錯(cuò)。
原因：全局配置僅放行l(wèi)ocalhost、127.0.0.1本地域名，未配置生產(chǎn)環(huán)境前端正式域名；生產(chǎn)環(huán)境前后端域名、端口不一致，觸發(fā)跨域攔截。
解決方案：在allowedOriginPatterns中添加生產(chǎn)前端域名，支持多域名配置，適配多環(huán)境部署。
坑點(diǎn)6：SpringSecurity 攔截跨域請(qǐng)求
報(bào)錯(cuò)現(xiàn)象：普通接口跨域正常，需要登錄認(rèn)證的接口跨域報(bào)錯(cuò)，控制臺(tái)403。
原因：SpringSecurity權(quán)限框架優(yōu)先級(jí)高于WebMvc跨域配置，預(yù)檢請(qǐng)求未攜帶Token，被安全攔截器攔截，導(dǎo)致跨域失效。
解決方案：使用CorsFilter過濾器方式配置跨域，同時(shí)在Security配置中開啟跨域支持，確保安全框架放行跨域請(qǐng)求。
五、前后端聯(lián)調(diào)標(biāo)準(zhǔn)化流程
為徹底避免聯(lián)調(diào)階段反復(fù)踩坑，整理一套標(biāo)準(zhǔn)化聯(lián)調(diào)流程，適配所有前后端分離項(xiàng)目：
- 后端統(tǒng)一配置全局跨域，刪除所有局部注解，統(tǒng)一跨域規(guī)則，放行所有請(qǐng)求方法、自定義請(qǐng)求頭、憑證；
- 后端配置完成后重啟項(xiàng)目，優(yōu)先測(cè)試OPTIONS預(yù)檢請(qǐng)求是否正常返回；
- 前端統(tǒng)一配置請(qǐng)求攔截器，固定請(qǐng)求頭格式，統(tǒng)一攜帶Token，避免請(qǐng)求頭不規(guī)范導(dǎo)致跨域；
- 開發(fā)環(huán)境使用通配符域名適配本地端口，生產(chǎn)環(huán)境配置正式域名，關(guān)閉全局通配符提升安全性；
- 結(jié)合前文接口日志功能，查看請(qǐng)求是否正常到達(dá)后端，區(qū)分是瀏覽器跨域攔截還是后端業(yè)務(wù)報(bào)錯(cuò)。
六、總結(jié)
跨域問題本質(zhì)不是Bug，而是瀏覽器的安全限制，絕大多數(shù)聯(lián)調(diào)跨域報(bào)錯(cuò)，都是配置不規(guī)范、版本不兼容、場(chǎng)景適配缺失導(dǎo)致。本文提供的三套全局跨域方案，覆蓋簡(jiǎn)單項(xiàng)目、通用項(xiàng)目、權(quán)限項(xiàng)目全場(chǎng)景，徹底替代零散的注解配置。
核心避坑要點(diǎn)：統(tǒng)一全局配置、禁止多方案混用、務(wù)必放行OPTIONS預(yù)檢請(qǐng)求、開啟憑證跨域適配Token登錄、區(qū)分Spring Boot版本差異、適配多環(huán)境域名。將該全局配置集成到項(xiàng)目中，可徹底解決前后端聯(lián)調(diào)所有跨域問題，保證項(xiàng)目從開發(fā)到上線全程穩(wěn)定可用。
到此這篇關(guān)于Spring Boot 全局跨域配置與前后端聯(lián)調(diào)避坑的文章就介紹到這了,更多相關(guān)Spring Boot 全局跨域配置與前后端聯(lián)調(diào)內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！
相關(guān)文章
在Spring?Boot項(xiàng)目中整合ZXing庫(kù)來生成二維碼是一個(gè)常見的需求,zxing是一個(gè)功能強(qiáng)大的開源Java庫(kù),專門用于二維碼的生成與解析,它支持Android、iOS、Java等多個(gè)平臺(tái),本文小編將給大家分享SpringBoot中生成二維碼的案例,需要的朋友可以參考下2024-08-08
Filter過濾器是javaWeb層面的,它跟Servlet類似,每次前端請(qǐng)求,首先進(jìn)入的是過濾器,我們必須實(shí)現(xiàn)Filter接口,重寫三個(gè)方法,才能使用Filter過濾器,需要的朋友可以參考下2021-06-06
Java比較器實(shí)現(xiàn)方法項(xiàng)目案例
這篇文章主要介紹了Java比較器實(shí)現(xiàn)方法,結(jié)合具體項(xiàng)目案例形式分析了Java比較器相關(guān)排序操作技巧,需要的朋友可以參考下2019-03-03
這篇文章主要介紹了Java多線程之Park和Unpark原理,需文中有非常詳細(xì)的代碼示例,對(duì)正在學(xué)習(xí)java的小伙伴們有非常好的幫助,要的朋友可以參考下2021-04-04
這篇文章主要介紹了java Mail郵件接收工具類,本文直接給出類實(shí)現(xiàn)代碼和使用示例,需要的朋友可以參考下2015-02-02
這篇文章主要介紹了Spring框架七大模塊簡(jiǎn)單介紹，具有一定參考價(jià)值，需要的朋友可以了解下。2017-11-11
SpringBoot Hutool各種用法示例小結(jié)
文章介紹了Hutool庫(kù)的使用,包括生成隨機(jī)數(shù)、對(duì)象信息過濾、生成UUID、MD5加密、JSON序列化和字段檢驗(yàn)等功能,并提供了詳細(xì)的用法示例,感興趣的朋友跟隨小編一起看看吧2026-01-01
Sentinel是一個(gè)高可用、高擴(kuò)展、高穩(wěn)定性的開源流量控制和熔斷降級(jí)框架，可以在分布式系統(tǒng)中實(shí)現(xiàn)實(shí)時(shí)的流量控制，防止系統(tǒng)因流量過大導(dǎo)致系統(tǒng)崩潰和服務(wù)降級(jí)，Sentinel面向所有的Java應(yīng)用，本文就給大家詳細(xì)介紹一下Java中Sentinel框架,需要的朋友可以參考下2023-06-06
用戶更新IDEA至2024.3,安裝配置proxyai插件,通過硅基流動(dòng)平臺(tái)注冊(cè)獲取免費(fèi)API配額,并設(shè)置模型參數(shù),最終完成工具配置使用2025-07-07
這篇文章主要介紹了SpringBoot如何打包自定義生成的包名問題，具有很好的參考價(jià)值，希望對(duì)大家有所幫助。如有錯(cuò)誤或未考慮完全的地方，望不吝賜教2023-06-06