1. 为什么要把 Vue3 前端塞进 SpringBoot 里跑单体部署的前因后果先聊一个很多人都会问的问题现在前端后端分离不是约定俗成了吗Vue3 打包出来的 dist 静态文件丢到 Nginx 或者对象存储里不香吗为什么非要塞进 SpringBoot 的 jar 包里我一开始也觉得这个操作有点逆潮流。实际做下来发现这种部署方式在特定场景下反而是最优解。最常见的情况是内部管理系统、中小型项目、以及客户要求“一个包带走”的交付场景。你想想Nginx 要单独装、要配反代、要考虑跨域而 SpringBoot 内嵌了 Tomcat天生就能托管静态资源——那你直接把 dist 扔进去一个 java -jar 就全起来了连端口都不用额外暴露。内网部署、客户现场交付、教学演示谁能拒绝这种省事还有一个现实痛点前后端分离之后跨域问题会一直缠着你。开发环境有 Vite proxy 帮你挡着打包上线之后如果没有 Nginx 做转发前端页面的 API 请求要么写死绝对地址要么被浏览器同源策略卡死。把前端页面交给 SpringBoot 托管让页面和接口同源跨域问题直接从根上消失。当然这个方案也有它的天花板静态资源交给 Java 容器托管吞吐量相比 Nginx 这类专业静态服务器还是有差距。所以它更适合中小企业内部系统、低并发的管理后台而不是面向公网的大流量 C 端应用。想明白自己的项目属于哪一类再决定要不要用这个方案。2. 前端构建的核心Vite 的 base 路径配置决定生死这一步是整条链路里最容易踩坑的地方。很多人打包完dist 文件一复制进 SpringBoot 的 static 目录打开页面发现白屏、控制台全是 404问题十有八九出在base路径上。2.1 绝对路径和相对路径到底差在哪Vite 的默认base值是/这意味着构建出的 index.html 里引用 JS 和 CSS 资源时路径是以根路径开头的script typemodule crossorigin src/assets/index-abc123.js/script这种绝对路径在两种情况下会直接翻车。第一种你的前端页面不是部署在域名根路径下而是部署在http://ip:8080/下的某个子路径里。第二种你访问页面时 Tomcat 配置了context-path比如server.servlet.context-path/myapp那么页面实际地址变成了http://ip:8080/myapp/但你 index.html 里引用的资源还是/assets/index-abc123.js——Tomcat 会去根的/assets目录找自然 404。解决思路很简单让构建出的资源路径是相对的或者显式指定成你部署的子路径。最省心的做法是把base设成./// vite.config.js export default defineConfig({ base: ./, // 其他配置... })./相对路径的好处是index.html 会引用相对自己路径下的资源不管你的静态文件被放到 Web 根目录还是子目录下只要 index.html 和资源文件夹的相对结构没变就能正常工作。2.2 多环境构建配置别把地址写死在代码里还有一个比路径更隐蔽的问题API 地址的环境切换。开发的时候你请求http://localhost:8080/api生产环境你在打包后希望请求http://你的服务器IP:8080/api如果用硬编码每个环境都得改一遍代码再重新打包非常痛苦。正确的做法是配合 Vite 的环境变量机制。在项目根目录创建三个文件.env.development开发环境变量.env.production生产环境变量如果还有测试环境再来一个.env.test内容大概是这样的# .env.production VITE_API_BASE_URL /api# .env.development VITE_API_BASE_URL /api然后在代码里统一通过import.meta.env.VITE_API_BASE_URL取这个变量。开发环境让 Vite 代理到后端生产环境直接同源访问代码里没有一处写死的主机名和端口。我见过太多项目上线后因为忘了改 API 地址页面能打开但所有数据都请求失败的案例了提前用环境变量规避掉是最明智的选择。3. 路由从 history 切换到 hash被白屏支配的恐惧如果你用 Vue Router 并且选择了createWebHistory()HTML5 History 模式打包部署到 SpringBoot 之后会遇到一个诡异的现象从首页点进去一切正常但只要刷新页面或者直接访问某个子路由地址Tomcat 就返回 404。3.1 404 的根源Tomcat 不知道你的前端路由要理解这个坑得先搞明白前端路由和后端路由的差异。History 模式下的路由本质上是一个“伪地址”——http://ip:8080/system/user这个 URL 在 SpringBoot 里并没有对应的 Controller 和 RequestMapping它只是前端 Router 内部维护的状态。当浏览器向 Tomcat 请求/system/user时Tomcat 在自己的路由表里找不到这个路径按默认规则就去static目录下找对应的静态文件也没有于是直接抛 404。你看到的白屏就这么来了。而 hash 模式createWebHashHistory()的 URL 长这样http://ip:8080/#/system/user#后面的部分不会被发送到服务器服务器永远只收到/这个请求自然就不会有这种问题。3.2 最省事的方案直接切 hash 模式如果你没有硬性要求 URL 必须好看或者项目是内部系统切换成 hash 模式是最稳的解法改一行代码的事import { createRouter, createWebHashHistory } from vue-router const router createRouter({ history: createWebHashHistory(), routes, })代价是 URL 里多了个#看起来稍微不那么“高级”但部署后彻底免疫刷新 404。3.3 想保留 history 模式给 SpringBoot 加一个路由兜底如果 URL 观感对你很重要想继续用 History 模式那就要让 SpringBoot 帮你兜底“所有未知路径都回退到 index.html”。实现方式不少我推荐最通用的一种写一个 Controller 来捕获未匹配路由。Controller public class PageForwardController { RequestMapping(value {/{path:[^\\.]*}, /{path:^(?!api).*}/**/{path:[^\\.]*}}) public String forward() { return forward:/index.html; } }这个 Controller 的关键在于路径正则。第一层{path:[^\\.]*}的意思是所有不带点号的单级路径都转发到 index.html避免误伤/assets/xxx.js、/images/logo.png这类带扩展名的静态资源。第二层处理多级路径比如/system/user。同时用负向前瞻(?!api)把后端 API 接口排除掉防止请求/api/xxx时也被转发到 index.html。配置完成后重启 SpringBoot 再试试直接刷新子路由页面就不会再 404 了。4. 资源放置与接口代理SpringBoot 里那些容易忽略的细节前端打包配置搞定接下来就是怎么把 dist 文件塞进 SpringBoot以及如何优雅地处理 API 请求路径。4.1 dist 文件放哪resources/static 还是静态资源目录SpringBoot 默认会从 classpath 下的static/、public/、resources/、META-INF/resources/这些目录里找静态资源优先级依次递减。所以最直接的做法是把 dist 文件夹里的所有文件直接放到src/main/resources/static/目录下让 index.html 在 static 根目录assets 文件夹也拷进去。有人习惯直接整个 dist 文件夹丢进去导致访问路径变成http://ip:8080/dist/index.html。这能用但多了一层不必要的目录。我建议把 dist 的内容平铺进 static这样你的页面地址就是干净的http://ip:8080/。如果你用的是 Maven 多模块结构可以把前端项目做成一个模块通过frontend-maven-plugin在 Maven 构建时自动执行npm install npm run build再把产物复制到 resources 下。这样团队其他人拉代码后一个mvn clean package就把前后端全部打出来了彻底告别手动拷文件的流程。这个进阶方案后面会专门展开。4.2 API 请求走相对路径的完整闭环前面提到使用环境变量VITE_API_BASE_URL这里把开发和生产两个场景串起来看。开发环境.env.development中设置VITE_API_BASE_URL /api同时 Vite 的 proxy 配置把/api开头的请求转发到后端服务// vite.config.js server: { proxy: { /api: { target: http://localhost:8080, changeOrigin: true, // 如果后端接口没有 /api 前缀可以 rewrite rewrite: (path) path.replace(/^\/api/, ), } } }生产环境把.env.production也设置成VITE_API_BASE_URL /api但不需要代码层面的代理。因为前端页面和 SpringBoot 已经是同源部署浏览器请求/api/user/list会直接打到你 SpringBoot 服务你的后端接口如果保持了/api前缀那就直接匹配如果后端接口没有前缀可以在 SpringBoot 的配置文件里加一层全局前缀Configuration public class WebMvcConfig implements WebMvcConfigurer { Override public void configurePathMatch(ConfigurablePathMatcher matcher) { // 或者通过 application.yml 配置 server.servlet.context-path 等方式处理 } }更简单的方式是直接用server.servlet.context-path/api把整个服务挂到/api前缀下。这样前端请求/api/user/list通过 context-path 自动映射到后端的/user/list不需要在代码层面做任何重写——一套逻辑贯穿开发和上线非常省心。4.3 同一个端口下的 Session 和 Cookie意外惊喜当页面和后端接口完全同源之后还有一个隐形福利Cookie 和 Session 不再有跨域问题。之前前后端分离部署时你总会遇到登录状态消失、Cookie 带不上这类头疼的问题需要额外配置withCredentials和跨域白名单。现在页面和接口在同一个端口下浏览器默认就会携带同源 Cookie登录认证一下子就安静了。5. 从手动到自动化Maven 插件把前后端打包成一体的进阶玩法基础的“手动打包 手动拷贝”能解决问题但体验太原始了。部署一次要执行两次构建、跨目录拷贝很容易搞漏文件。在多次重复这个流程之后我决定把整个过程收编到 Maven 构建生命周期里。5.1 用 frontend-maven-plugin 替代命令行构建在 pom.xml 里配置frontend-maven-plugin它会自动帮你下载指定版本的 Node 和 npm第一次构建时会下载到本地仓库然后执行构建命令。核心配置大概是这样的plugin groupIdcom.github.eirslett/groupId artifactIdfrontend-maven-plugin/artifactId version1.15.0/version configuration workingDirectorysrc/main/frontend/workingDirectory installDirectorytarget/installDirectory /configuration executions execution idinstall node and npm/id goals goalinstall-node-and-npm/goal /goals configuration nodeVersionv18.20.4/nodeVersion npmVersion10.7.0/npmVersion /configuration /execution execution idnpm install/id goals goalnpm/goal /goals configuration argumentsinstall/arguments /configuration /execution execution idnpm run build/id goals goalnpm/goal /goals configuration argumentsrun build/arguments /configuration /execution /executions /plugin这里有个细节执行npm run build之后需要确保构建产物能进入 SpringBoot 的 classpath。可以在maven-resources-plugin里配置把src/main/frontend/dist复制到target/classes/staticplugin groupIdorg.apache.maven.plugins/groupId artifactIdmaven-resources-plugin/artifactId executions execution idcopy-frontend-dist/id phaseprocess-resources/phase goals goalcopy-resources/goal /goals configuration outputDirectory${project.build.outputDirectory}/static/outputDirectory resources resource directorysrc/main/frontend/dist/directory /resource /resources /configuration /execution /executions /plugin这么一套配置下来以后部署只需要三步mvn clean package拿到一个 fat jar然后java -jar app.jar。以前那种“前端构建一小时后端构建五分钟最后发现拷错文件”的日子是一去不复返了。5.2 CI/CD 场景下的流水线配置参考如果你们公司有 Jenkins 或者 GitLab CI这套 Maven 配置也能无缝衔接。整个流水线只需要一个 Maven 任务比如 Jenkins Pipeline 里的核心阶段stage(Build) { steps { sh mvn clean package -DskipTests } }不需要为前端单独配置 Node 环境因为 frontend-maven-plugin 会在构建时自动下载对应版本的 Node。不过有个小提示第一次构建会比较慢因为要下载 Node 和 npm 依赖建议把installDirectory设置成固定目录并让 CI 缓存住。6. 打包部署后的常见症状与排查思路把最常见的几种“打包完成后运行异常”的症状列出来你可以对照自己的情况快速定位。症状可能原因解法页面白屏控制台 JS 404Vue 资源路径是绝对路径/assets/xxx但应用部署在子路径下修改 Vite 的base为./重新构建子路由刷新后 404History 模式下 Tomcat 无对应路由切换到 hash 模式或者添加 Controller forward 兜底页面页面能打开接口请求 404前端请求路径和后端 context-path/Controller 路径不匹配统一 API 前缀检查请求路径与服务端路由是否一致页面能打开但接口请求跨域报错前端部署的 origin 和后端接口 origin 不一致让静态资源和接口同源部署或正确配置 CORSCSS 样式全丢了构建后 CSS 引入路径错误或静态资源被拦截检查 base 配置检查 SpringBoot 是否配置了拦截器挡住了静态资源部署新版本后页面还显示旧内容浏览器缓存了旧的 index.html 或 JS/CSS给资源文件名加 hashVite 默认会加或配置 Nginx/容器层禁用 HTML 缓存这里额外多说几句关于VITE_API_BASE_URL的坑。很多人设了生产环境变量为http://localhost:8080/api结果部署到服务器上页面前端是能打开了但所有请求都往用户本地的 8080 打——这种粗心的低级错误我见过不止一次。记住生产环境的 API 地址一般应保持相对路径/api和页面保持同源不要写绝对地址。还有一个 SpringBoot 拦截器层面的问题。如果你的项目里注册了 HandlerInterceptor 来校验登录态比如判断 Session 里有没有用户信息那么前端静态资源请求.js、.css、.png也有可能被拦截器拦下来。Vue 构建的 index.html 加载后一连串的资源请求全被返回 401页面就会处于半残废状态。处理方式是放行静态资源路径registry.addInterceptor(loginInterceptor) .addPathPatterns(/**) .excludePathPatterns(/, /index.html, /assets/**, /favicon.ico);7. 优化思路CDN、缓存与构建体积的控制把 Vue3 项目塞进 SpringBoot 只是第一步上线之后还可以做几个锦上添花的优化。比较大的项目建议把第三方库Vue、Element Plus、Axios 等从业务代码中分离出去。vite-plugin-cdn-import可以把这些库改成 CDN 引入打包体积立竿见影地降下来——业务代码和第三方框架的体积本来就是两个量级。不过要注意CDN 地址必须是内网可达的有些客户现场是离线环境那这就行不通需要把这些库文件手动下载下来放进 static 目录。构建产物的缓存策略也值得花点心思。Vite 默认会对带 hash 的文件名设置很长的缓存周期但对 index.html 推荐设置为no-cache确保每次发布后用户能拿到新的入口文件。如果是内网系统直接在 SpringBoot 里写个简单的配置类设置响应头也行Configuration public class StaticResourceCacheConfig implements WebMvcConfigurer { Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler(/assets/**) .addResourceLocations(classpath:/static/assets/) .setCachePeriod(3600 * 24 * 30); // 30天 } }这种细控制的好处是一旦前端发布了新版本带新 hash 的资源文件名会变index.html 第一时间拉到新文件而旧的资源文件依然可以被浏览器缓存命中不会因为强制刷新造成性能浪费。8. 实操中的最终验证清单与体会把一套流程跑顺之后我习惯在部署完成后过一遍自检清单按顺序确认每一项都通过才敢说“部署完成”浏览器直接打开部署地址/首页能正常渲染打开控制台 NetWork 面板确认没有 JS、CSS 的 404 或 500点击进入一个二级页面手动刷新确认页面不报 404检查接口请求路径全部是同源的/api开头没有跨域报错登录退出流程走一遍确认 Cookie/Session 正常工作在服务器命令行执行curl -I http://localhost:8080/确认响应头正常我个人在实际操作中的体会是最折腾人的其实是“路径”这个看似简单的问题——前端资源和接口的绝对路径、相对路径、子路径一多起来就特别容易埋雷。但只要理解了base、context-path、路由模式这几个关键位置的原理这套部署方案在稳定性上几乎不需要再操什么心。以后遇到新项目如果需求是内网部署、交付给客户、或者是内部后台我都会优先考虑这个方案而不是直接上 Nginx。最后再分享一个小技巧如果你是在 IDEA 里本地联调想临时模拟生产环境的效果不用每次真的打包成 jar。直接在 IDEA 的 Run Configuration 里指定working directory为项目根目录然后跑 SpringBoot 启动类再把 dist 里的文件放到target/classes/static一样能复现线上部署的完整行为。用这种方式做集成测试比反复打包高效得多。
