建集成實操指南)
最近在開發(fā)一個前后端分離項目時用 Vite 作為前端構(gòu)建工具、Maven 作為后端工程管理工具結(jié)果在環(huán)境兼容、跨域代理、構(gòu)建產(chǎn)物提交這幾個環(huán)節(jié)反復(fù)踩坑。網(wǎng)上的資料大多只講了其中某一段很少有人把「Vite Maven」這對組合從零到一完整串起來。本文整理了一份閉環(huán)實操方案包含前后端工程結(jié)構(gòu)劃分、代理配置、打包聯(lián)動、本地聯(lián)調(diào)以及常見報錯排查適合正在做前后端分離項目、準(zhǔn)備把構(gòu)建流程整合起來的新手也適合需要快速搭一套可維護工程骨架的后端開發(fā)?！竀xM」在這篇文章里特指 Vite Maven 的技術(shù)組合“cp 向自行避雷”的意思是如果你準(zhǔn)備用這對組合管理前后端項目哪些地方容易出問題、哪些配置別亂改我會把容易踩的坑提前標(biāo)注出來方便你自行避讓。1. Vite 與 Maven 分別解決什么問題1.1 Maven 在項目里的定位Maven 是 Java 生態(tài)里非常經(jīng)典的構(gòu)建工具核心能力是依賴管理和生命周期管理。你在pom.xml里聲明需要哪些第三方庫Maven 會從中央倉庫把對應(yīng)版本的 jar 包下載到本地倉庫并在打包時將這些依賴按作用域compile、provided、runtime、test處理進最終產(chǎn)物。此外Maven 把項目構(gòu)建過程拆成了標(biāo)準(zhǔn)生命周期比如validate - compile - test - package - verify - install - deploy這意味著你不需要手動去下載 jar、不需要自己敲 javac 編譯命令只需要執(zhí)行mvn clean package就可以完成從清理到打包的全部步驟。對于多人協(xié)作的 Java 項目來說統(tǒng)一構(gòu)建命令、統(tǒng)一依賴版本、統(tǒng)一打包產(chǎn)物結(jié)構(gòu)價值非常大。1.2 Vite 在項目里的定位Vite 是前端構(gòu)建工具定位是開發(fā)體驗好、構(gòu)建速度快。它底層利用瀏覽器原生 ES Module 的能力在開發(fā)環(huán)境不需要像 Webpack 那樣先把所有模塊打包完再啟動服務(wù)而是按需編譯所以冷啟動非?？?。生產(chǎn)構(gòu)建時則使用 Rollup 來打包最終輸出靜態(tài)資源。Vite 的核心配置文件是vite.config.js可以配置開發(fā)服務(wù)器端口、代理、別名、構(gòu)建輸出目錄、環(huán)境變量等。配合 React 或 Vue 使用非常方便。1.3 為什么要把 Vite 和 Maven 放在一起大部分后端項目并不只是提供接口還需要把前端構(gòu)建出來的靜態(tài)資源嵌入到 Spring Boot 的 jar 包中實現(xiàn)一個“單一可部署產(chǎn)物”。如果前端構(gòu)建和后端打包完全分離會出現(xiàn)幾個問題前端改完代碼后需要手動執(zhí)行構(gòu)建命令再把dist目錄拷貝到后端resources/static下過程繁瑣且容易漏。團隊協(xié)作時前端產(chǎn)物可能沒有及時提交后端人員打包后運行的是舊的靜態(tài)頁面。本地聯(lián)調(diào)時如果前端開發(fā)服務(wù)器和后端接口服務(wù)端口不一致跨域問題會反復(fù)出現(xiàn)。通過 Maven 插件把 Vite 構(gòu)建過程集成進來可以實現(xiàn)執(zhí)行mvn clean package時自動先構(gòu)建前端資源再將構(gòu)建產(chǎn)物復(fù)制到后端靜態(tài)資源目錄最后統(tǒng)一打包成可運行的 jar。2. 環(huán)境準(zhǔn)備與項目結(jié)構(gòu)說明2.1 基礎(chǔ)環(huán)境本文示例環(huán)境如下工具版本建議JDK1.8 及以上Maven3.6 及以上Node.js16 及以上npm 或 pnpmnpm 8 或 pnpm 7Spring Boot2.7.x按實際項目調(diào)整Vite4.x按實際項目調(diào)整如果本機還沒裝 Node.js 和 Maven可以先執(zhí)行下面兩條命令確認(rèn)環(huán)境mvn -v node -v如果命令提示找不到說明環(huán)境變量沒有配置好需要先安裝對應(yīng)的運行環(huán)境。這里的版本并不是硬性要求你完全可以根據(jù)公司已有技術(shù)棧調(diào)整本文重點演示配置方式和組合思路。2.2 推薦的項目目錄結(jié)構(gòu)為了讓前后端代碼在同一個倉庫里管理又避免互相干擾推薦采用下面的結(jié)構(gòu)vxm-demo/ ├── pom.xml ├── src/ │ └── main/ │ ├── java/ │ ├── resources/ │ └── vue-app/ # 前端項目 │ ├── package.json │ ├── vite.config.js │ ├── index.html │ └── src/ │ ├── main.js │ ├── App.vue │ └── components/ └── docs/把前端項目放在src/main/vue-app下而不是單獨放在倉庫根目錄的平行目錄是為了讓 Maven 在構(gòu)建時可以直接定位到前端源碼目錄減少路徑穿越的配置成本。當(dāng)然如果你更傾向于把frontend目錄放在根目錄也是可以的只要 Maven 插件里的workingDirectory配置對應(yīng)調(diào)整。3. 核心配置拆解Maven 集成 Vite 構(gòu)建3.1 使用 frontend-maven-plugin在 Maven 里集成前端構(gòu)建最常用的插件是frontend-maven-plugin它可以自動下載 Node.js 和 npm然后執(zhí)行npm install與npm run build。下面是一個基礎(chǔ)的配置示例放在pom.xml的buildplugins中plugin groupIdcom.github.eirslett/groupId artifactIdfrontend-maven-plugin/artifactId version1.12.1/version configuration workingDirectorysrc/main/vue-app/workingDirectory /configuration executions execution idinstall node and npm/id goals goalinstall-node-and-npm/goal /goals phasegenerate-resources/phase configuration nodeVersionv16.20.2/nodeVersion npmVersion8.19.4/npmVersion /configuration /execution execution idnpm install/id goals goalnpm/goal /goals phasegenerate-resources/phase configuration argumentsinstall/arguments /configuration /execution execution idnpm build/id goals goalnpm/goal /goals phasegenerate-resources/phase configuration argumentsrun build/arguments /configuration /execution /executions /plugin幾個關(guān)鍵點需要說明workingDirectory指定了前端項目的根目錄也就是package.json所在的位置。install-node-and-npm會自動下載對應(yīng)版本的 Node.js 和 npm。如果本地已經(jīng)安裝了 Node.js可以去掉這一步但考慮到團隊新成員環(huán)境可能不統(tǒng)一保留會更省心。三個 execution 都綁定在generate-resources階段這個階段在compile之前可以保證前端構(gòu)建產(chǎn)物先就緒后續(xù)復(fù)制資源時不會找不到目錄。另一種做法是使用exec-maven-plugin直接調(diào)用本機的npm命令。這種方式不會自動安裝 Node.js但可以利用本機已有的 npm 鏡像配置速度可能更快。示例plugin groupIdorg.codehaus.mojo/groupId artifactIdexec-maven-plugin/artifactId version3.1.0/version executions execution idexec-npm-install/id phasegenerate-resources/phase configuration workingDirectorysrc/main/vue-app/workingDirectory executablenpm/executable arguments argumentinstall/argument /arguments /configuration goals goalexec/goal /goals /execution execution idexec-npm-build/id phasegenerate-resources/phase configuration workingDirectorysrc/main/vue-app/workingDirectory executablenpm/executable arguments argumentrun/argument argumentbuild/argument /arguments /configuration goals goalexec/goal /goals /execution /executions /plugin3.2 將 dist 目錄復(fù)制到 Spring Boot 靜態(tài)資源目錄前端npm run build之后產(chǎn)物默認(rèn)在src/main/vue-app/dist目錄。為了讓 Spring Boot 能直接托管這些靜態(tài)資源需要將dist里的內(nèi)容復(fù)制到src/main/resources/static。Spring Boot 默認(rèn)會從以下位置加載靜態(tài)資源classpath:/static/ classpath:/public/ classpath:/resources/ classpath:/META-INF/resources/因此把前端構(gòu)建產(chǎn)物放到classpath:/static/下是最直接的方式。復(fù)制操作可以使用maven-resources-plugin完成plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-resources-plugin/artifactId executions execution idcopy-vue-dist/id phaseprepare-package/phase goals goalcopy-resources/goal /goals configuration outputDirectory${project.build.outputDirectory}/static/outputDirectory resources resource directorysrc/main/vue-app/dist/directory /resource /resources /configuration /execution /executions /pluginprepare-package階段位于compile之后、package之前此時編譯產(chǎn)物已經(jīng)生成復(fù)制進target/classes/static后最終會被放進 jar 包。這里有一個容易踩的坑如果輸出目錄寫成了src/main/resources/static可能會污染本地的源碼目錄尤其在使用 git 時會產(chǎn)生大量不需要提交的變動。推薦直接輸出到target/classes/static保證源碼目錄干凈。3.3 配置 Vite 的 base 路徑前端構(gòu)建時生成的資源路徑默認(rèn)是/如果你的后端接口整體帶有上下文路徑比如http://localhost:8080/project-name/就需要在vite.config.js中配置base。打開前端目錄下的vite.config.jsimport { defineConfig } from vite import vue from vitejs/plugin-vue export default defineConfig({ base: ./, plugins: [vue()], server: { port: 3000, host: 0.0.0.0, proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } }, build: { outDir: dist, assetsDir: assets } })base: /是默認(rèn)值適用于部署在域名根路徑的場景。如果改成base: ./構(gòu)建出來的 HTML 資源路徑會變成相對路徑方便直接部署在任意子目錄或者通過 jar 包訪問時減少路徑問題。proxy配置是本地聯(lián)調(diào)的關(guān)鍵。開發(fā)時 Vite 服務(wù)器默認(rèn)跑在3000端口后端接口在8080端口如果不配置代理瀏覽器直接請求http://localhost:8080/api會跨域。配置代理后前端代碼里請求/api時Vite 會在開發(fā)服務(wù)器層面把請求轉(zhuǎn)發(fā)到后端瀏覽器的同源策略限制就不存在了。4. 完整實戰(zhàn)搭建一個 Vite Spring Boot Maven 項目4.1 創(chuàng)建后端工程骨架先用 Spring Initializr 或者手工創(chuàng)建 Maven 工程核心是pom.xml包含 Spring Boot 相關(guān)依賴。假設(shè)項目名稱為vxm-demopom.xml關(guān)鍵內(nèi)容如下parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.17/version relativePath/ /parent properties java.version1.8/java.version node.versionv16.20.2/node.version npm.version8.19.4/npm.version /properties dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency /dependencies創(chuàng)建主啟動類// 文件路徑src/main/java/com/example/vxmdemo/VxmDemoApplication.java package com.example.vxmdemo; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; SpringBootApplication public class VxmDemoApplication { public static void main(String[] args) { SpringApplication.run(VxmDemoApplication.class, args); } }創(chuàng)建一個簡單的接口用于聯(lián)調(diào)// 文件路徑src/main/java/com/example/vxmdemo/controller/HelloController.java package com.example.vxmdemo.controller; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; import java.util.HashMap; import java.util.Map; RestController RequestMapping(/api) public class HelloController { GetMapping(/hello) public MapString, String hello() { MapString, String result new HashMap(); result.put(message, Hello from Spring Boot); return result; } }4.2 創(chuàng)建前端工程在前端目錄src/main/vue-app下初始化項目。如果目錄不存在先創(chuàng)建mkdir -p src/main/vue-app然后進入目錄初始化package.jsoncd src/main/vue-app npm init -y安裝 Vue 和 Vitenpm install vue3 npm install vite4 vitejs/plugin-vue --save-dev為了方便npm run build調(diào)用構(gòu)建命令在package.json中配置 scripts{ name: vue-app, version: 1.0.0, scripts: { dev: vite, build: vite build, preview: vite preview }, dependencies: { vue: ^3.3.4 }, devDependencies: { vitejs/plugin-vue: ^4.2.3, vite: ^4.4.9 } }創(chuàng)建index.html!-- 文件路徑src/main/vue-app/index.html -- !DOCTYPE html html langzh-CN head meta charsetUTF-8 / meta nameviewport contentwidthdevice-width, initial-scale1.0 / titleVite Maven Demo/title /head body div idapp/div script typemodule src/src/main.js/script /body /html創(chuàng)建前端入口文件// 文件路徑src/main/vue-app/src/main.js import { createApp } from vue import App from ./App.vue createApp(App).mount(#app)創(chuàng)建根組件!-- 文件路徑src/main/vue-app/src/App.vue -- template div stylefont-family: Arial, sans-serif; padding: 20px; h1Vite Maven 工程演示/h1 p{{ message }}/p button clickfetchMessage請求后端接口/button /div /template script setup import { ref } from vue const message ref(點擊按鈕請求 Spring Boot 接口) async function fetchMessage() { const response await fetch(/api/hello) const data await response.json() message.value data.message } /script這里的fetch(/api/hello)在開發(fā)環(huán)境會通過 Vite 代理轉(zhuǎn)發(fā)到后端在生產(chǎn)環(huán)境則會直接訪問同源地址下的/api/hello所以不需要區(qū)分環(huán)境地址。4.3 配置前端代理在src/main/vue-app目錄下創(chuàng)建vite.config.js// 文件路徑src/main/vue-app/vite.config.js import { defineConfig } from vite import vue from vitejs/plugin-vue export default defineConfig({ base: ./, plugins: [vue()], server: { port: 3000, host: 0.0.0.0, proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } }, build: { outDir: dist, assetsDir: assets } })這里需要特別解釋changeOrigin的作用。當(dāng) Vite 代理轉(zhuǎn)發(fā)請求時請求頭里的Host默認(rèn)是localhost:3000如果后端服務(wù)對Host有校驗可能會拒絕請求或者會因為虛擬主機配置而路由錯誤。設(shè)置changeOrigin: true后代理會重寫請求的Host為target的主機名避免這類問題。4.4 完整 pom.xml 配置把前面的內(nèi)容整合到項目的pom.xmlproject modelVersion4.0.0/modelVersion parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.17/version relativePath/ /parent groupIdcom.example/groupId artifactIdvxm-demo/artifactId version1.0.0/version packagingjar/packaging properties java.version1.8/java.version node.versionv16.20.2/node.version npm.version8.19.4/npm.version /properties dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency /dependencies build plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId /plugin plugin groupIdcom.github.eirslett/groupId artifactIdfrontend-maven-plugin/artifactId version1.12.1/version configuration workingDirectorysrc/main/vue-app/workingDirectory /configuration executions execution idinstall node and npm/id goals goalinstall-node-and-npm/goal /goals phasegenerate-resources/phase configuration nodeVersion${node.version}/nodeVersion npmVersion${npm.version}/npmVersion /configuration /execution execution idnpm install/id goals goalnpm/goal /goals phasegenerate-resources/phase configuration argumentsinstall/arguments /configuration /execution execution idnpm build/id goals goalnpm/goal /goals phasegenerate-resources/phase configuration argumentsrun build/arguments /configuration /execution /executions /plugin plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-resources-plugin/artifactId executions execution idcopy-vue-dist/id phaseprepare-package/phase goals goalcopy-resources/goal /goals configuration outputDirectory${project.build.outputDirectory}/static/outputDirectory resources resource directorysrc/main/vue-app/dist/directory /resource /resources /configuration /execution /executions /plugin /plugins /build /project4.5 運行與驗證先啟動后端服務(wù)mvn spring-boot:run后端默認(rèn)端口是 8080通過http://localhost:8080/api/hello可以驗證接口是否正常。然后啟動前端開發(fā)服務(wù)器cd src/main/vue-app npm run dev瀏覽器訪問http://localhost:3000點擊頁面按鈕如果能看到后端返回的消息說明代理生效前后端聯(lián)調(diào)正常。接下來測試整體打包mvn clean package打包完成后查看target目錄ls -lh target/*.jar運行 jarjava -jar target/vxm-demo-1.0.0.jar訪問http://localhost:8080/可以看到前端頁面點擊按鈕也能正常請求后端接口。這說明前端資源已經(jīng)被正確打進 jar 包。4.6 注意事項首次構(gòu)建時間較長使用frontend-maven-plugin時第一次執(zhí)行構(gòu)建會自動下載 Node.js 和 npm耗時取決于網(wǎng)絡(luò)狀況。如果公司網(wǎng)絡(luò)訪問 Node 官方源較慢可以通過設(shè)置nodeDownloadRoot和npmDownloadRoot參數(shù)指定鏡像地址。也可以跳過自動下載直接使用本地 Node.js用exec-maven-plugin方案代替。5. 常見問題與排查思路5.1 前端構(gòu)建產(chǎn)物沒有復(fù)制到 static 目錄問題現(xiàn)象執(zhí)行mvn clean package后target/classes/static目錄不存在或者 jar 包中沒有前端頁面。常見原因maven-resources-plugin的復(fù)制階段配置錯誤。前端構(gòu)建過程沒有被觸發(fā)。src/main/vue-app/dist目錄不存在說明npm run build失敗。解決思路在本地手動執(zhí)行前端構(gòu)建確認(rèn)能否生成dist目錄cd src/main/vue-app npm install npm run build如果構(gòu)建成功再檢查pom.xml中插件的執(zhí)行階段和輸出目錄是否正確。5.2 前端頁面能打開但接口請求 404問題現(xiàn)象訪問http://localhost:8080/能看到頁面但點擊按鈕后接口返回 404。常見原因前端構(gòu)建時請求的接口路徑是/api/hello后端接口地址不匹配。Spring Boot 的 context-path 配置有值比如server.servlet.context-path/demo導(dǎo)致實際接口地址變成/demo/api/hello。接口所在的 Controller 類沒有被掃描到。解決思路先用 curl 直接測試后端接口curl http://localhost:8080/api/hello如果接口返回數(shù)據(jù)說明后端正常問題出在前端路徑。如果返回 404檢查RestController的注解、SpringBootApplication所在的包路徑以及application.properties中的context-path配置。5.3 開發(fā)環(huán)境跨域請求失敗問題現(xiàn)象前端頁面跑在 3000 端口直接請求 8080 端口的接口瀏覽器控制臺報 CORS 錯誤。常見原因Vite 代理未生效。proxy配置路徑寫錯。前端請求地址寫了全路徑比如http://localhost:8080/api/hello沒有走/api開頭的相對路徑。解決思路檢查瀏覽器請求的 URL如果是http://localhost:3000/api/hello說明代理生效。如果請求直接指向了http://localhost:8080則需要修改前端請求代碼使用/api/hello。另外確認(rèn) Vite 配置文件的修改已經(jīng)生效。Vite 開發(fā)服務(wù)器并不一定會自動重啟修改vite.config.js后建議重啟npm run dev。5.4 Maven 構(gòu)建時報 npm 命令找不到問題現(xiàn)象Failed to execute goal com.github.eirslett:frontend-maven-plugin:1.12.1:npm (npm install) on project vxm-demo: The npm command could not be found.常見原因install-node-and-npm執(zhí)行失敗Node.js 沒有下載成功。workingDirectory配置的路徑?jīng)]有找到package.json。系統(tǒng)代理或鏡像源問題導(dǎo)致下載超時。解決思路先檢查target目錄下是否有 Maven 自動下載的 Node.js 文件比如node目錄。如果為空說明下載步驟失敗了可以嘗試設(shè)置鏡像源configuration nodeDownloadRoothttps://npmmirror.com/mirrors/node//nodeDownloadRoot npmDownloadRoothttps://npmmirror.com/mirrors/npm//npmDownloadRoot /configuration也可以換成exec-maven-plugin方案直接使用本機已安裝的 Node.js 和 npm。5.5 打包后靜態(tài)資源加載 404問題現(xiàn)象jar 包運行后訪問根路徑出現(xiàn) 404 或者頁面空白。常見原因靜態(tài)資源沒有打包進classpath:/static/。Vite 構(gòu)建的index.html里的資源路徑不對。前端路由使用的是 history 模式刷新后交給后端處理但后端沒有對應(yīng)的路由轉(zhuǎn)發(fā)配置。解決思路先確認(rèn) jar 包中是否包含靜態(tài)資源jar tf target/vxm-demo-1.0.0.jar | grep static如果沒有輸出說明復(fù)制階段出問題。如果有輸出再看index.html的引用路徑。如果前端使用了vue-router的history模式還需要在后端處理前端路由的 fallback但這超出了本文范圍建議先使用hash模式避免該問題。排查清單如下問題現(xiàn)象常見原因解決思路接口 404請求路徑和后端RequestMapping不匹配用 curl 測試接口比對路徑接口 404context-path導(dǎo)致地址前綴變化檢查application.properties或yml中的server.servlet.context-path跨域報錯前端請求走了全路徑改成/api/xx相對路徑交給代理轉(zhuǎn)發(fā)跨域報錯Vite 代理配置未重啟修改vite.config.js后重啟開發(fā)服務(wù)器打包后頁面空白dist里資源路徑是絕對路徑/assets/xx.js修改base: ./后重新構(gòu)建打包后頁面空白前端路由 history 模式刷新 404改用 hash 模式或配置后端 fallback首次構(gòu)建很慢Maven 下載 Node.js/npm 超時配置鏡像源替換下載地址6. 最佳實踐與工程建議6.1 明確前后端邊界Vite Maven 的組合容易給人一種“前后端代碼放一起”的錯覺但在實際開發(fā)中建議嚴(yán)格區(qū)分模塊邊界后端接口不要依賴前端工程里的任何代碼。前端代碼不要直接引用后端 Java 類。前后端通過 HTTP 接口通信接口的入?yún)?、出參、錯誤碼要提前定義好。在項目結(jié)構(gòu)上前端代碼只是后端構(gòu)建時的一個構(gòu)建產(chǎn)物來源而不是后端項目的一部分。6.2 使用環(huán)境變量區(qū)分部署場景Vite 支持通過環(huán)境變量區(qū)分開發(fā)、測試、生產(chǎn)環(huán)境。你可以在前端目錄下創(chuàng)建.env.development和.env.production文件分別寫入不同的配置項。例如# .env.development VITE_API_BASE/api# .env.production VITE_API_BASE/api然后在代碼中使用import.meta.env.VITE_API_BASE拼接接口路徑。這樣可以避免在代碼中寫死環(huán)境地址。不過要注意Vite 環(huán)境變量默認(rèn)只在構(gòu)建時生效運行時修改不會生效。6.3 Maven 構(gòu)建與前端構(gòu)建解耦如果你的團隊中有人不需要改前端代碼每次執(zhí)行mvn clean package都要等前端構(gòu)建完成體驗不夠好。可以通過 Maven Profile 來區(qū)分是否構(gòu)建前端。例如profiles profile idbuild-frontend/id activation activeByDefaulttrue/activeByDefault /activation build plugins !-- 前端構(gòu)建和復(fù)制插件放在這里 -- /plugins /build /profile /profiles當(dāng)需要跳過前端構(gòu)建時執(zhí)行mvn clean package -P !build-frontend或者直接設(shè)置 Maven 屬性跳過mvn clean package -DskipFrontendtrue在插件配置里通過屬性判斷是否需要執(zhí)行這樣更靈活。6.4 統(tǒng)一 npm 鏡像源為了避免團隊中不同成員的 npm 下載速度差異可以在前端目錄下創(chuàng)建.npmrc文件registryhttps://registry.npmmirror.com這會強制 npm 使用鏡像源減少 install 時間。當(dāng)然如果你的網(wǎng)絡(luò)環(huán)境可以直接訪問官方源也可以不配置。6.5 安全邊界與部署建議前端資源打包進 jar 包適合中小型應(yīng)用、內(nèi)部系統(tǒng)、單體服務(wù)。如果你的應(yīng)用訪問量很大或需要獨立擴容前端靜態(tài)資源更推薦將前端資源部署到 Nginx、OSS、CDN而不是打進 Java 進程里。在生產(chǎn)環(huán)境部署時需要注意后端接口不要暴露到公網(wǎng)除非有明確需求和權(quán)限控制。配置 HTTPS 后注意前端資源中是否含有明文 http 請求。如果前端資源中有敏感信息比如密鑰、API Token不要寫在前端代碼中。使用 Spring Security 時靜態(tài)資源是否需要認(rèn)證要根據(jù)業(yè)務(wù)決定。如果是控制臺類系統(tǒng)通常需要登錄后訪問此時需要放行登錄頁相關(guān)資源但保護接口。6.6 資源目錄不要提交到 Gitnode_modules、dist、target這些目錄都不應(yīng)該提交到版本控制中。建議在.gitignore中配置target/ node_modules/ src/main/vue-app/dist/ *.log .DS_Store這樣團隊成員克隆代碼后執(zhí)行構(gòu)建會自動生成這些目錄不會因為本地產(chǎn)物不同而產(chǎn)生沖突。7. 總結(jié)與下一步學(xué)習(xí)建議通過這篇文章你應(yīng)該掌握了 Vite 與 Maven 組合使用的基本思路前端代碼由 Maven 插件統(tǒng)一構(gòu)建構(gòu)建產(chǎn)物自動復(fù)制到 Spring Boot 靜態(tài)資源目錄最終打包成一個可運行的 jar 包。同時也了解了本地開發(fā)時如何通過 Vite 代理解決跨域問題、生產(chǎn)環(huán)境如何檢查靜態(tài)資源是否打包成功以及常見的幾個報錯點如何排查。如果你準(zhǔn)備在團隊中落地這種模式建議先從一個小項目開始嘗試跑通后再推廣到正式項目。重點觀察首次構(gòu)建時間、團隊成員本機環(huán)境差異、前端依賴升級對構(gòu)建的影響這三個方面。穩(wěn)定的構(gòu)建流程需要逐步調(diào)優(yōu)不要期望一次配置就能覆蓋所有場景。更進一步的優(yōu)化方向包括前端使用pnpm替代 npm提升依賴安裝速度。將前端構(gòu)建步驟用 Docker Multi-stage 獨立出來減少構(gòu)建機器依賴。使用spring-boot-maven-plugin的layers功能優(yōu)化 jar 包分層。前端增加 ESLint、單元測試、代碼規(guī)范檢查與 Maven 生命周期結(jié)合讓壞代碼在package之前就暴露出來。引入接口文檔工具保證前后端并行開發(fā)時接口定義清晰。如果你對這套配置有什么坑要補充歡迎在評論區(qū)留言。后面我也會繼續(xù)分享 Spring Boot 靜態(tài)資源處理、前端構(gòu)建性能優(yōu)化、Maven Profile 多環(huán)境部署等相關(guān)內(nèi)容。 Vite + Maven 前后端分離項目構(gòu)建集成實操指南
最近在開發(fā)一個前后端分離項目時用 Vite 作為前端構(gòu)建工具、Maven 作為后端工程管理工具結(jié)果在環(huán)境兼容、跨域代理、構(gòu)建產(chǎn)物提交這幾個環(huán)節(jié)反復(fù)踩坑。網(wǎng)上的資料大多只講了其中某一段很少有人把「Vite Maven」這對組合從零到一完整串起來。本文整理了一份閉環(huán)實操方案包含前后端工程結(jié)構(gòu)劃分、代理配置、打包聯(lián)動、本地聯(lián)調(diào)以及常見報錯排查適合正在做前后端分離項目、準(zhǔn)備把構(gòu)建流程整合起來的新手也適合需要快速搭一套可維護工程骨架的后端開發(fā)?！竀xM」在這篇文章里特指 Vite Maven 的技術(shù)組合“cp 向自行避雷”的意思是如果你準(zhǔn)備用這對組合管理前后端項目哪些地方容易出問題、哪些配置別亂改我會把容易踩的坑提前標(biāo)注出來方便你自行避讓。1. Vite 與 Maven 分別解決什么問題1.1 Maven 在項目里的定位Maven 是 Java 生態(tài)里非常經(jīng)典的構(gòu)建工具核心能力是依賴管理和生命周期管理。你在pom.xml里聲明需要哪些第三方庫Maven 會從中央倉庫把對應(yīng)版本的 jar 包下載到本地倉庫并在打包時將這些依賴按作用域compile、provided、runtime、test處理進最終產(chǎn)物。此外Maven 把項目構(gòu)建過程拆成了標(biāo)準(zhǔn)生命周期比如validate - compile - test - package - verify - install - deploy這意味著你不需要手動去下載 jar、不需要自己敲 javac 編譯命令只需要執(zhí)行mvn clean package就可以完成從清理到打包的全部步驟。對于多人協(xié)作的 Java 項目來說統(tǒng)一構(gòu)建命令、統(tǒng)一依賴版本、統(tǒng)一打包產(chǎn)物結(jié)構(gòu)價值非常大。1.2 Vite 在項目里的定位Vite 是前端構(gòu)建工具定位是開發(fā)體驗好、構(gòu)建速度快。它底層利用瀏覽器原生 ES Module 的能力在開發(fā)環(huán)境不需要像 Webpack 那樣先把所有模塊打包完再啟動服務(wù)而是按需編譯所以冷啟動非?？?。生產(chǎn)構(gòu)建時則使用 Rollup 來打包最終輸出靜態(tài)資源。Vite 的核心配置文件是vite.config.js可以配置開發(fā)服務(wù)器端口、代理、別名、構(gòu)建輸出目錄、環(huán)境變量等。配合 React 或 Vue 使用非常方便。1.3 為什么要把 Vite 和 Maven 放在一起大部分后端項目并不只是提供接口還需要把前端構(gòu)建出來的靜態(tài)資源嵌入到 Spring Boot 的 jar 包中實現(xiàn)一個“單一可部署產(chǎn)物”。如果前端構(gòu)建和后端打包完全分離會出現(xiàn)幾個問題前端改完代碼后需要手動執(zhí)行構(gòu)建命令再把dist目錄拷貝到后端resources/static下過程繁瑣且容易漏。團隊協(xié)作時前端產(chǎn)物可能沒有及時提交后端人員打包后運行的是舊的靜態(tài)頁面。本地聯(lián)調(diào)時如果前端開發(fā)服務(wù)器和后端接口服務(wù)端口不一致跨域問題會反復(fù)出現(xiàn)。通過 Maven 插件把 Vite 構(gòu)建過程集成進來可以實現(xiàn)執(zhí)行mvn clean package時自動先構(gòu)建前端資源再將構(gòu)建產(chǎn)物復(fù)制到后端靜態(tài)資源目錄最后統(tǒng)一打包成可運行的 jar。2. 環(huán)境準(zhǔn)備與項目結(jié)構(gòu)說明2.1 基礎(chǔ)環(huán)境本文示例環(huán)境如下工具版本建議JDK1.8 及以上Maven3.6 及以上Node.js16 及以上npm 或 pnpmnpm 8 或 pnpm 7Spring Boot2.7.x按實際項目調(diào)整Vite4.x按實際項目調(diào)整如果本機還沒裝 Node.js 和 Maven可以先執(zhí)行下面兩條命令確認(rèn)環(huán)境mvn -v node -v如果命令提示找不到說明環(huán)境變量沒有配置好需要先安裝對應(yīng)的運行環(huán)境。這里的版本并不是硬性要求你完全可以根據(jù)公司已有技術(shù)棧調(diào)整本文重點演示配置方式和組合思路。2.2 推薦的項目目錄結(jié)構(gòu)為了讓前后端代碼在同一個倉庫里管理又避免互相干擾推薦采用下面的結(jié)構(gòu)vxm-demo/ ├── pom.xml ├── src/ │ └── main/ │ ├── java/ │ ├── resources/ │ └── vue-app/ # 前端項目 │ ├── package.json │ ├── vite.config.js │ ├── index.html │ └── src/ │ ├── main.js │ ├── App.vue │ └── components/ └── docs/把前端項目放在src/main/vue-app下而不是單獨放在倉庫根目錄的平行目錄是為了讓 Maven 在構(gòu)建時可以直接定位到前端源碼目錄減少路徑穿越的配置成本。當(dāng)然如果你更傾向于把frontend目錄放在根目錄也是可以的只要 Maven 插件里的workingDirectory配置對應(yīng)調(diào)整。3. 核心配置拆解Maven 集成 Vite 構(gòu)建3.1 使用 frontend-maven-plugin在 Maven 里集成前端構(gòu)建最常用的插件是frontend-maven-plugin它可以自動下載 Node.js 和 npm然后執(zhí)行npm install與npm run build。下面是一個基礎(chǔ)的配置示例放在pom.xml的buildplugins中plugin groupIdcom.github.eirslett/groupId artifactIdfrontend-maven-plugin/artifactId version1.12.1/version configuration workingDirectorysrc/main/vue-app/workingDirectory /configuration executions execution idinstall node and npm/id goals goalinstall-node-and-npm/goal /goals phasegenerate-resources/phase configuration nodeVersionv16.20.2/nodeVersion npmVersion8.19.4/npmVersion /configuration /execution execution idnpm install/id goals goalnpm/goal /goals phasegenerate-resources/phase configuration argumentsinstall/arguments /configuration /execution execution idnpm build/id goals goalnpm/goal /goals phasegenerate-resources/phase configuration argumentsrun build/arguments /configuration /execution /executions /plugin幾個關(guān)鍵點需要說明workingDirectory指定了前端項目的根目錄也就是package.json所在的位置。install-node-and-npm會自動下載對應(yīng)版本的 Node.js 和 npm。如果本地已經(jīng)安裝了 Node.js可以去掉這一步但考慮到團隊新成員環(huán)境可能不統(tǒng)一保留會更省心。三個 execution 都綁定在generate-resources階段這個階段在compile之前可以保證前端構(gòu)建產(chǎn)物先就緒后續(xù)復(fù)制資源時不會找不到目錄。另一種做法是使用exec-maven-plugin直接調(diào)用本機的npm命令。這種方式不會自動安裝 Node.js但可以利用本機已有的 npm 鏡像配置速度可能更快。示例plugin groupIdorg.codehaus.mojo/groupId artifactIdexec-maven-plugin/artifactId version3.1.0/version executions execution idexec-npm-install/id phasegenerate-resources/phase configuration workingDirectorysrc/main/vue-app/workingDirectory executablenpm/executable arguments argumentinstall/argument /arguments /configuration goals goalexec/goal /goals /execution execution idexec-npm-build/id phasegenerate-resources/phase configuration workingDirectorysrc/main/vue-app/workingDirectory executablenpm/executable arguments argumentrun/argument argumentbuild/argument /arguments /configuration goals goalexec/goal /goals /execution /executions /plugin3.2 將 dist 目錄復(fù)制到 Spring Boot 靜態(tài)資源目錄前端npm run build之后產(chǎn)物默認(rèn)在src/main/vue-app/dist目錄。為了讓 Spring Boot 能直接托管這些靜態(tài)資源需要將dist里的內(nèi)容復(fù)制到src/main/resources/static。Spring Boot 默認(rèn)會從以下位置加載靜態(tài)資源classpath:/static/ classpath:/public/ classpath:/resources/ classpath:/META-INF/resources/因此把前端構(gòu)建產(chǎn)物放到classpath:/static/下是最直接的方式。復(fù)制操作可以使用maven-resources-plugin完成plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-resources-plugin/artifactId executions execution idcopy-vue-dist/id phaseprepare-package/phase goals goalcopy-resources/goal /goals configuration outputDirectory${project.build.outputDirectory}/static/outputDirectory resources resource directorysrc/main/vue-app/dist/directory /resource /resources /configuration /execution /executions /pluginprepare-package階段位于compile之后、package之前此時編譯產(chǎn)物已經(jīng)生成復(fù)制進target/classes/static后最終會被放進 jar 包。這里有一個容易踩的坑如果輸出目錄寫成了src/main/resources/static可能會污染本地的源碼目錄尤其在使用 git 時會產(chǎn)生大量不需要提交的變動。推薦直接輸出到target/classes/static保證源碼目錄干凈。3.3 配置 Vite 的 base 路徑前端構(gòu)建時生成的資源路徑默認(rèn)是/如果你的后端接口整體帶有上下文路徑比如http://localhost:8080/project-name/就需要在vite.config.js中配置base。打開前端目錄下的vite.config.jsimport { defineConfig } from vite import vue from vitejs/plugin-vue export default defineConfig({ base: ./, plugins: [vue()], server: { port: 3000, host: 0.0.0.0, proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } }, build: { outDir: dist, assetsDir: assets } })base: /是默認(rèn)值適用于部署在域名根路徑的場景。如果改成base: ./構(gòu)建出來的 HTML 資源路徑會變成相對路徑方便直接部署在任意子目錄或者通過 jar 包訪問時減少路徑問題。proxy配置是本地聯(lián)調(diào)的關(guān)鍵。開發(fā)時 Vite 服務(wù)器默認(rèn)跑在3000端口后端接口在8080端口如果不配置代理瀏覽器直接請求http://localhost:8080/api會跨域。配置代理后前端代碼里請求/api時Vite 會在開發(fā)服務(wù)器層面把請求轉(zhuǎn)發(fā)到后端瀏覽器的同源策略限制就不存在了。4. 完整實戰(zhàn)搭建一個 Vite Spring Boot Maven 項目4.1 創(chuàng)建后端工程骨架先用 Spring Initializr 或者手工創(chuàng)建 Maven 工程核心是pom.xml包含 Spring Boot 相關(guān)依賴。假設(shè)項目名稱為vxm-demopom.xml關(guān)鍵內(nèi)容如下parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.17/version relativePath/ /parent properties java.version1.8/java.version node.versionv16.20.2/node.version npm.version8.19.4/npm.version /properties dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency /dependencies創(chuàng)建主啟動類// 文件路徑src/main/java/com/example/vxmdemo/VxmDemoApplication.java package com.example.vxmdemo; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; SpringBootApplication public class VxmDemoApplication { public static void main(String[] args) { SpringApplication.run(VxmDemoApplication.class, args); } }創(chuàng)建一個簡單的接口用于聯(lián)調(diào)// 文件路徑src/main/java/com/example/vxmdemo/controller/HelloController.java package com.example.vxmdemo.controller; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; import java.util.HashMap; import java.util.Map; RestController RequestMapping(/api) public class HelloController { GetMapping(/hello) public MapString, String hello() { MapString, String result new HashMap(); result.put(message, Hello from Spring Boot); return result; } }4.2 創(chuàng)建前端工程在前端目錄src/main/vue-app下初始化項目。如果目錄不存在先創(chuàng)建mkdir -p src/main/vue-app然后進入目錄初始化package.jsoncd src/main/vue-app npm init -y安裝 Vue 和 Vitenpm install vue3 npm install vite4 vitejs/plugin-vue --save-dev為了方便npm run build調(diào)用構(gòu)建命令在package.json中配置 scripts{ name: vue-app, version: 1.0.0, scripts: { dev: vite, build: vite build, preview: vite preview }, dependencies: { vue: ^3.3.4 }, devDependencies: { vitejs/plugin-vue: ^4.2.3, vite: ^4.4.9 } }創(chuàng)建index.html!-- 文件路徑src/main/vue-app/index.html -- !DOCTYPE html html langzh-CN head meta charsetUTF-8 / meta nameviewport contentwidthdevice-width, initial-scale1.0 / titleVite Maven Demo/title /head body div idapp/div script typemodule src/src/main.js/script /body /html創(chuàng)建前端入口文件// 文件路徑src/main/vue-app/src/main.js import { createApp } from vue import App from ./App.vue createApp(App).mount(#app)創(chuàng)建根組件!-- 文件路徑src/main/vue-app/src/App.vue -- template div stylefont-family: Arial, sans-serif; padding: 20px; h1Vite Maven 工程演示/h1 p{{ message }}/p button clickfetchMessage請求后端接口/button /div /template script setup import { ref } from vue const message ref(點擊按鈕請求 Spring Boot 接口) async function fetchMessage() { const response await fetch(/api/hello) const data await response.json() message.value data.message } /script這里的fetch(/api/hello)在開發(fā)環(huán)境會通過 Vite 代理轉(zhuǎn)發(fā)到后端在生產(chǎn)環(huán)境則會直接訪問同源地址下的/api/hello所以不需要區(qū)分環(huán)境地址。4.3 配置前端代理在src/main/vue-app目錄下創(chuàng)建vite.config.js// 文件路徑src/main/vue-app/vite.config.js import { defineConfig } from vite import vue from vitejs/plugin-vue export default defineConfig({ base: ./, plugins: [vue()], server: { port: 3000, host: 0.0.0.0, proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } }, build: { outDir: dist, assetsDir: assets } })這里需要特別解釋changeOrigin的作用。當(dāng) Vite 代理轉(zhuǎn)發(fā)請求時請求頭里的Host默認(rèn)是localhost:3000如果后端服務(wù)對Host有校驗可能會拒絕請求或者會因為虛擬主機配置而路由錯誤。設(shè)置changeOrigin: true后代理會重寫請求的Host為target的主機名避免這類問題。4.4 完整 pom.xml 配置把前面的內(nèi)容整合到項目的pom.xmlproject modelVersion4.0.0/modelVersion parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.17/version relativePath/ /parent groupIdcom.example/groupId artifactIdvxm-demo/artifactId version1.0.0/version packagingjar/packaging properties java.version1.8/java.version node.versionv16.20.2/node.version npm.version8.19.4/npm.version /properties dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency /dependencies build plugins plugin groupIdorg.springframework.boot/groupId artifactIdspring-boot-maven-plugin/artifactId /plugin plugin groupIdcom.github.eirslett/groupId artifactIdfrontend-maven-plugin/artifactId version1.12.1/version configuration workingDirectorysrc/main/vue-app/workingDirectory /configuration executions execution idinstall node and npm/id goals goalinstall-node-and-npm/goal /goals phasegenerate-resources/phase configuration nodeVersion${node.version}/nodeVersion npmVersion${npm.version}/npmVersion /configuration /execution execution idnpm install/id goals goalnpm/goal /goals phasegenerate-resources/phase configuration argumentsinstall/arguments /configuration /execution execution idnpm build/id goals goalnpm/goal /goals phasegenerate-resources/phase configuration argumentsrun build/arguments /configuration /execution /executions /plugin plugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-resources-plugin/artifactId executions execution idcopy-vue-dist/id phaseprepare-package/phase goals goalcopy-resources/goal /goals configuration outputDirectory${project.build.outputDirectory}/static/outputDirectory resources resource directorysrc/main/vue-app/dist/directory /resource /resources /configuration /execution /executions /plugin /plugins /build /project4.5 運行與驗證先啟動后端服務(wù)mvn spring-boot:run后端默認(rèn)端口是 8080通過http://localhost:8080/api/hello可以驗證接口是否正常。然后啟動前端開發(fā)服務(wù)器cd src/main/vue-app npm run dev瀏覽器訪問http://localhost:3000點擊頁面按鈕如果能看到后端返回的消息說明代理生效前后端聯(lián)調(diào)正常。接下來測試整體打包mvn clean package打包完成后查看target目錄ls -lh target/*.jar運行 jarjava -jar target/vxm-demo-1.0.0.jar訪問http://localhost:8080/可以看到前端頁面點擊按鈕也能正常請求后端接口。這說明前端資源已經(jīng)被正確打進 jar 包。4.6 注意事項首次構(gòu)建時間較長使用frontend-maven-plugin時第一次執(zhí)行構(gòu)建會自動下載 Node.js 和 npm耗時取決于網(wǎng)絡(luò)狀況。如果公司網(wǎng)絡(luò)訪問 Node 官方源較慢可以通過設(shè)置nodeDownloadRoot和npmDownloadRoot參數(shù)指定鏡像地址。也可以跳過自動下載直接使用本地 Node.js用exec-maven-plugin方案代替。5. 常見問題與排查思路5.1 前端構(gòu)建產(chǎn)物沒有復(fù)制到 static 目錄問題現(xiàn)象執(zhí)行mvn clean package后target/classes/static目錄不存在或者 jar 包中沒有前端頁面。常見原因maven-resources-plugin的復(fù)制階段配置錯誤。前端構(gòu)建過程沒有被觸發(fā)。src/main/vue-app/dist目錄不存在說明npm run build失敗。解決思路在本地手動執(zhí)行前端構(gòu)建確認(rèn)能否生成dist目錄cd src/main/vue-app npm install npm run build如果構(gòu)建成功再檢查pom.xml中插件的執(zhí)行階段和輸出目錄是否正確。5.2 前端頁面能打開但接口請求 404問題現(xiàn)象訪問http://localhost:8080/能看到頁面但點擊按鈕后接口返回 404。常見原因前端構(gòu)建時請求的接口路徑是/api/hello后端接口地址不匹配。Spring Boot 的 context-path 配置有值比如server.servlet.context-path/demo導(dǎo)致實際接口地址變成/demo/api/hello。接口所在的 Controller 類沒有被掃描到。解決思路先用 curl 直接測試后端接口curl http://localhost:8080/api/hello如果接口返回數(shù)據(jù)說明后端正常問題出在前端路徑。如果返回 404檢查RestController的注解、SpringBootApplication所在的包路徑以及application.properties中的context-path配置。5.3 開發(fā)環(huán)境跨域請求失敗問題現(xiàn)象前端頁面跑在 3000 端口直接請求 8080 端口的接口瀏覽器控制臺報 CORS 錯誤。常見原因Vite 代理未生效。proxy配置路徑寫錯。前端請求地址寫了全路徑比如http://localhost:8080/api/hello沒有走/api開頭的相對路徑。解決思路檢查瀏覽器請求的 URL如果是http://localhost:3000/api/hello說明代理生效。如果請求直接指向了http://localhost:8080則需要修改前端請求代碼使用/api/hello。另外確認(rèn) Vite 配置文件的修改已經(jīng)生效。Vite 開發(fā)服務(wù)器并不一定會自動重啟修改vite.config.js后建議重啟npm run dev。5.4 Maven 構(gòu)建時報 npm 命令找不到問題現(xiàn)象Failed to execute goal com.github.eirslett:frontend-maven-plugin:1.12.1:npm (npm install) on project vxm-demo: The npm command could not be found.常見原因install-node-and-npm執(zhí)行失敗Node.js 沒有下載成功。workingDirectory配置的路徑?jīng)]有找到package.json。系統(tǒng)代理或鏡像源問題導(dǎo)致下載超時。解決思路先檢查target目錄下是否有 Maven 自動下載的 Node.js 文件比如node目錄。如果為空說明下載步驟失敗了可以嘗試設(shè)置鏡像源configuration nodeDownloadRoothttps://npmmirror.com/mirrors/node//nodeDownloadRoot npmDownloadRoothttps://npmmirror.com/mirrors/npm//npmDownloadRoot /configuration也可以換成exec-maven-plugin方案直接使用本機已安裝的 Node.js 和 npm。5.5 打包后靜態(tài)資源加載 404問題現(xiàn)象jar 包運行后訪問根路徑出現(xiàn) 404 或者頁面空白。常見原因靜態(tài)資源沒有打包進classpath:/static/。Vite 構(gòu)建的index.html里的資源路徑不對。前端路由使用的是 history 模式刷新后交給后端處理但后端沒有對應(yīng)的路由轉(zhuǎn)發(fā)配置。解決思路先確認(rèn) jar 包中是否包含靜態(tài)資源jar tf target/vxm-demo-1.0.0.jar | grep static如果沒有輸出說明復(fù)制階段出問題。如果有輸出再看index.html的引用路徑。如果前端使用了vue-router的history模式還需要在后端處理前端路由的 fallback但這超出了本文范圍建議先使用hash模式避免該問題。排查清單如下問題現(xiàn)象常見原因解決思路接口 404請求路徑和后端RequestMapping不匹配用 curl 測試接口比對路徑接口 404context-path導(dǎo)致地址前綴變化檢查application.properties或yml中的server.servlet.context-path跨域報錯前端請求走了全路徑改成/api/xx相對路徑交給代理轉(zhuǎn)發(fā)跨域報錯Vite 代理配置未重啟修改vite.config.js后重啟開發(fā)服務(wù)器打包后頁面空白dist里資源路徑是絕對路徑/assets/xx.js修改base: ./后重新構(gòu)建打包后頁面空白前端路由 history 模式刷新 404改用 hash 模式或配置后端 fallback首次構(gòu)建很慢Maven 下載 Node.js/npm 超時配置鏡像源替換下載地址6. 最佳實踐與工程建議6.1 明確前后端邊界Vite Maven 的組合容易給人一種“前后端代碼放一起”的錯覺但在實際開發(fā)中建議嚴(yán)格區(qū)分模塊邊界后端接口不要依賴前端工程里的任何代碼。前端代碼不要直接引用后端 Java 類。前后端通過 HTTP 接口通信接口的入?yún)?、出參、錯誤碼要提前定義好。在項目結(jié)構(gòu)上前端代碼只是后端構(gòu)建時的一個構(gòu)建產(chǎn)物來源而不是后端項目的一部分。6.2 使用環(huán)境變量區(qū)分部署場景Vite 支持通過環(huán)境變量區(qū)分開發(fā)、測試、生產(chǎn)環(huán)境。你可以在前端目錄下創(chuàng)建.env.development和.env.production文件分別寫入不同的配置項。例如# .env.development VITE_API_BASE/api# .env.production VITE_API_BASE/api然后在代碼中使用import.meta.env.VITE_API_BASE拼接接口路徑。這樣可以避免在代碼中寫死環(huán)境地址。不過要注意Vite 環(huán)境變量默認(rèn)只在構(gòu)建時生效運行時修改不會生效。6.3 Maven 構(gòu)建與前端構(gòu)建解耦如果你的團隊中有人不需要改前端代碼每次執(zhí)行mvn clean package都要等前端構(gòu)建完成體驗不夠好。可以通過 Maven Profile 來區(qū)分是否構(gòu)建前端。例如profiles profile idbuild-frontend/id activation activeByDefaulttrue/activeByDefault /activation build plugins !-- 前端構(gòu)建和復(fù)制插件放在這里 -- /plugins /build /profile /profiles當(dāng)需要跳過前端構(gòu)建時執(zhí)行mvn clean package -P !build-frontend或者直接設(shè)置 Maven 屬性跳過mvn clean package -DskipFrontendtrue在插件配置里通過屬性判斷是否需要執(zhí)行這樣更靈活。6.4 統(tǒng)一 npm 鏡像源為了避免團隊中不同成員的 npm 下載速度差異可以在前端目錄下創(chuàng)建.npmrc文件registryhttps://registry.npmmirror.com這會強制 npm 使用鏡像源減少 install 時間。當(dāng)然如果你的網(wǎng)絡(luò)環(huán)境可以直接訪問官方源也可以不配置。6.5 安全邊界與部署建議前端資源打包進 jar 包適合中小型應(yīng)用、內(nèi)部系統(tǒng)、單體服務(wù)。如果你的應(yīng)用訪問量很大或需要獨立擴容前端靜態(tài)資源更推薦將前端資源部署到 Nginx、OSS、CDN而不是打進 Java 進程里。在生產(chǎn)環(huán)境部署時需要注意后端接口不要暴露到公網(wǎng)除非有明確需求和權(quán)限控制。配置 HTTPS 后注意前端資源中是否含有明文 http 請求。如果前端資源中有敏感信息比如密鑰、API Token不要寫在前端代碼中。使用 Spring Security 時靜態(tài)資源是否需要認(rèn)證要根據(jù)業(yè)務(wù)決定。如果是控制臺類系統(tǒng)通常需要登錄后訪問此時需要放行登錄頁相關(guān)資源但保護接口。6.6 資源目錄不要提交到 Gitnode_modules、dist、target這些目錄都不應(yīng)該提交到版本控制中。建議在.gitignore中配置target/ node_modules/ src/main/vue-app/dist/ *.log .DS_Store這樣團隊成員克隆代碼后執(zhí)行構(gòu)建會自動生成這些目錄不會因為本地產(chǎn)物不同而產(chǎn)生沖突。7. 總結(jié)與下一步學(xué)習(xí)建議通過這篇文章你應(yīng)該掌握了 Vite 與 Maven 組合使用的基本思路前端代碼由 Maven 插件統(tǒng)一構(gòu)建構(gòu)建產(chǎn)物自動復(fù)制到 Spring Boot 靜態(tài)資源目錄最終打包成一個可運行的 jar 包。同時也了解了本地開發(fā)時如何通過 Vite 代理解決跨域問題、生產(chǎn)環(huán)境如何檢查靜態(tài)資源是否打包成功以及常見的幾個報錯點如何排查。如果你準(zhǔn)備在團隊中落地這種模式建議先從一個小項目開始嘗試跑通后再推廣到正式項目。重點觀察首次構(gòu)建時間、團隊成員本機環(huán)境差異、前端依賴升級對構(gòu)建的影響這三個方面。穩(wěn)定的構(gòu)建流程需要逐步調(diào)優(yōu)不要期望一次配置就能覆蓋所有場景。更進一步的優(yōu)化方向包括前端使用pnpm替代 npm提升依賴安裝速度。將前端構(gòu)建步驟用 Docker Multi-stage 獨立出來減少構(gòu)建機器依賴。使用spring-boot-maven-plugin的layers功能優(yōu)化 jar 包分層。前端增加 ESLint、單元測試、代碼規(guī)范檢查與 Maven 生命周期結(jié)合讓壞代碼在package之前就暴露出來。引入接口文檔工具保證前后端并行開發(fā)時接口定義清晰。如果你對這套配置有什么坑要補充歡迎在評論區(qū)留言。后面我也會繼續(xù)分享 Spring Boot 靜態(tài)資源處理、前端構(gòu)建性能優(yōu)化、Maven Profile 多環(huán)境部署等相關(guān)內(nèi)容。