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