Vue Spring Boot 这种前后端分离组合这几年几乎是中小型项目的标配。前端打包成静态文件扔进 Spring Boot 的static目录或者干脆打成 jar 一起部署省事又方便。但只要前端路由用了 History 模式十有八九会遇到一个让人挠头的问题首页能开点着跳转也没毛病一旦你在某个子路由页面按一下 F5 刷新页面直接 404。这个项目标题里提到的 History模式 打包后 刷新404 问题我之前在好几个项目里都踩过也帮别人排查过很多次。今天就把这个问题的原理、解决方案、以及那些容易让人栽跟头的细节一次性说透。先说结论这个问题几乎不是代码逻辑 bug而是前后端对“路由”这件事的理解不一致。前端 History 模式把路由交给了浏览器地址栏后端却只认识静态文件路径和 Controller 映射两边没对齐一刷新自然就找不到页面了。文章后面我会给出三种可靠的解决方案并详细对照它们的适用场景同时把部署到独立服务器使用 Nginx和打成 jar 包内嵌 Tomcat这两种常见方式都覆盖到。1. 问题现象与根因分析1.1 为什么 Hash 模式没事History 模式一刷新就出事很多初学者第一次遇到这个问题时第一反应是“打包打错了”或者“代码写错了”其实不然。要理解这个问题得先搞清楚两种路由模式在浏览器层面的本质区别。Hash 模式URL 长这样http://xxx.com/#/dashboard。注意这个#号它后面的所有内容都只是浏览器端的一个锚点标记永远不会发送到服务器。你刷新页面时浏览器实际请求的是http://xxx.com/服务器返回index.html然后前端路由再根据当前的#/dashboard去渲染对应组件。所以无论你怎么刷新请求的路径都没变服务器永远能正确返回首页文件。History 模式URL 长这样http://xxx.com/dashboard。这是利用浏览器 H5 的history.pushState实现的地址栏路径看起来和正常后端接口路径一样。但是问题来了当你在/dashboard这个路径下按 F5 刷新时浏览器会向服务器发起一个真实的 HTTP 请求请求路径就是/dashboard。Spring Boot 收到这个请求后在它的视角里没有哪个RequestMapping(/dashboard)与之对应static目录下也没有叫dashboard的静态文件那该怎么办只能返回 404。类比一下就像你在一家实体图书馆里看书Hash 模式相当于你随手夹了一张书签无论你翻到哪一页重新打开书还是回到扉页再跳转而 History 模式相当于你在书里的第 80 页压了一个角下次从书架拿下来你希望直接翻到第 80 页但图书管理员并不知道你要的是第 80 页他只能告诉你“这页不存在”。这就是根因。1.2 服务器视角的请求流转过程为了更清晰地定位问题我们可以把一次刷新请求在 Spring Boot 内部经历的过程拆开看浏览器发起GET /dashboard请求。请求进入 Spring Boot 的 DispatcherServlet 前端控制器。前端控制器查询是否有名为/dashboard的RequestMapping映射。没有。前端控制器尝试查找/dashboard对应的静态资源。Tomcat 默认的静态资源处理器会在classpath:/static/等目录下寻找同名文件。没有。找不到对应资源抛出NoResourceFoundExceptionSpring Boot 3.x或NoHandlerFoundExceptionSpring Boot 2.x最终返回 404。所以你看整个流程里没有一个环节知道“/dashboard是一个前端路由你应该返回index.html”。我们要做的就是在这一步之间加一个“兜底策略”把所有非静态资源的、没有后端 Controller 匹配的请求统一转发到index.html。2. 三种务实解决方案对比2.1 方案一重写 ErrorController统一转发到 index.html这是很多老项目里常见的做法原理是拦截 Spring Boot 的/error跳转把 404 请求重定向到首页。实现起来逻辑直观但有个小坑需要注意。首先定义错误页面转发逻辑核心代码如下RestController public class NotFoundController implements ErrorController { // Spring Boot 2.x 用这个方法 // public String getErrorPath() { // return /error; // } RequestMapping(/error) public ModelAndView handleError(HttpServletRequest request) { Object status request.getAttribute(RequestDispatcher.ERROR_STATUS_CODE); if (status ! null Integer.parseInt(status.toString()) 404) { // 返回 200 状态码否则浏览器会认为此次请求失败了 return new ModelAndView(forward:/index.html); } return new ModelAndView(forward:/error.html); } }这里我要强调一个关键点返回的必须是forward:/index.html而不是redirect:/index.html。两者的区别在于forward是服务器内部转发浏览器地址栏保持/dashboard不变所有资源加载相对路径时依然以/dashboard为基准适合 SPA 场景而redirect是让浏览器重新发起一个请求到/地址栏会变成https://xxx.com/刷新后路由状态丢失用户体验打折但也能解决 404 问题。这个方案的优点是实现简单几行代码就能搞定且兼容性强基本适配 Spring Boot 2.x 和 3.x。缺点是本质上依赖 Spring Boot 的错误处理链路在遇到某些非 404 错误时比如 500也可能会被误拦截需要代码里做状态码判断。2.2 方案二实现 WebMvcConfigurer 添加视图控制器最推荐这个方案我认为是最优雅、最可控的。利用addViewControllers方法显式声明“只要请求路径满足某类条件就直接转发到 index.html”。Configuration public class WebConfig implements WebMvcConfigurer { Override public void addViewControllers(ViewControllerRegistry registry) { // 所有路径都转发到 index.html但排除实际存在的静态资源路径 registry.addViewController(/{spring:[a-zA-Z0-9\\-\\_]}) .setViewName(forward:/index.html); registry.addViewController(/**/{spring:[a-zA-Z0-9\\-\\_]}) .setViewName(forward:/index.html); registry.addViewController(/{spring:[a-zA-Z0-9\\-\\_]}/**{spring2:[a-zA-Z0-9\\-\\_]}) .setViewName(forward:/index.html); } }看一眼可能有点懵这三个表达式是什么意思其实它们是用来匹配“看起来像前端路由的路径”的。第一个匹配一级路径如/dashboard。第二个匹配多级路径如/user/profile。第三个匹配一级路径加多级子路径的组合。这里的正则表达式[a-zA-Z0-9\\-\\_]限制了匹配的字符集。为什么不用/**直接匹配所有路径因为那样会把.js、.css、.png等静态资源也全部拦截并转发到index.html导致页面样式全部丢失。这个正则保证了路径中不包含点号因为点号不在字符集里也就意味着所有带文件扩展名的真实静态资源请求会被自动排除在外。这个方案的好处是精准、高效且对 API 请求无影响你的真实接口还是走RestController映射不会被视图控制器拦截。如果你是 Spring Boot 3.x 用户我强烈建议优先采用这个方案。2.3 方案三部署在 Nginx 时用 try_files 解决虽然标题里写的是 Spring Boot但现实中有很多项目是 Vue 打包产物部署在 Nginx然后 Nginx 反向代理到 Spring Boot API。这种情况下问题发生在 Nginx 层面解决方式完全不同。Nginx 配置的核心是try_files指令server { listen 80; server_name yourdomain.com; root /opt/vue-dist; index index.html; location / { try_files $uri $uri/ /index.html; } location /api/ { proxy_pass http://backend-server:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }这个配置的含义是当一个请求进来时Nginx 先尝试匹配真实存在的文件$uri再尝试匹配目录$uri/如果都不存在就回退到/index.html。这个方案里有一个容易忽略的细节location /只处理前端路由location /api/单独处理后端接口。如果你把所有请求都交给try_files回退到index.html那么/api/login这类接口请求也找不到对应文件也会被回退导致接口 404。所以必须把 API 请求单独拎出来配转发这就是我上面配置里第二段location的意义。3. 从打包到部署的完整实操记录3.1 前端构建配置调整我来模拟一次完整操作。比如一个典型项目前端用 Vue 3 Vite后端是 Spring Boot 3.x最终希望打成单个 jar 包部署到一个低配云服务器上。前端先执行npm run build产物默认输出到dist目录。构建之前必须确认两个配置Vite 的base配置如果打算 jar 包解压后直接访问根路径即http://ip:8080/base可以保持默认的/。如果打算部署在子路径下比如http://ip:8080/app/base必须设置为/app/否则打包出的index.html里引用的 JS 和 CSS 路径全是/assets/xxx.js和实际部署路径不符页面会白屏。路由的createWebHistory(base)参数这个base参数需要与 Vite 的base保持一致。通常我们在router/index.js里写createWebHistory(import.meta.env.BASE_URL)Vite 会自动读取base配置这也是官方推荐的写法能避免很多路径问题。3.2 将前端产物打包进 Spring Boot有两种方式把前端产物放进后端工程直接复制到src/main/resources/static目录下然后随工程一起打包。使用 Maven 插件如frontend-maven-plugin在构建后端 jar 时自动执行前端构建命令并复制产物。多用于 CI/CD 流水线。我手动操作时倾向于第一种简单直接。将dist目录下的所有文件复制到src/main/resources/static后启动 Spring Boot访问http://localhost:8080/应该能正常看到首页。此时在浏览器地址栏输入http://localhost:8080/dashboard点回车大概率还是 404。这正是预期现象因为我们还没配置转发规则。3.3 实战配置 History 模式兼容根据第 2 节的分析我推荐直接采用方案二WebMvcConfigurer。把它写进后端配置类Configuration public class SpaForwardConfig implements WebMvcConfigurer { Override public void addViewControllers(ViewControllerRegistry registry) { // 匹配单级路由和多级路由排除带扩展名的静态资源 String pathPattern /{path:[^\\.]*}; registry.addViewController(pathPattern).setViewName(forward:/index.html); String deepPathPattern /**/{path:[^\\.]*}; registry.addViewController(deepPathPattern).setViewName(forward:/index.html); } }这里我把正则从原版方案简化成了[^\\.]*匹配不含点号的任意字符效果相同且更容易理解。配置完成后重启应用刷新/dashboard这次能正常看到页面了。一个重要提示这种方法成功后你会发现访问任意一个不存在的路径比如/abc/xyz/foo都会返回index.html的 200 响应。这是因为前端路由接管了 URL 后会尝试匹配abc/xyz/foo对应的路由匹配不到就渲染 404 页面前提是你配置了前端路由的通配符兜底。这是正常现象SPA 的精髓就是页面路由由前端管理后端只管提供入口。3.4 内嵌 Tomcat 的替代方案RewriteValve如果你不想改 Java 代码或者你是运维人员不方便动代码还有一招是用 Tomcat 的 RewriteValve。Spring Boot 内嵌 Tomcat 也支持这个组件需要在src/main/resources/META-INF/目录下放context.xml并且在conf/下放rewrite.config。配置示例!-- META-INF/context.xml -- Context Valve classNameorg.apache.catalina.valves.rewrite.RewriteValve / /Context# 重写规则 RewriteCond %{REQUEST_URI} !^/static/.* RewriteCond %{REQUEST_URI} !^/api/.* RewriteRule ^/(.*)$ /index.html [L]这个方案优点是不用改 Java 类只改配置缺点是意味着你对所有非静态、非 API 的请求都做了重写且要手动指定排除规则。配置项可读性不强排错也麻烦一些。如果你用的是 Spring Boot 3.x基于 Tomcat 10这个 RewriteValve 的包名和装载机制可能会有些许变化踩坑成本略高。所以我个人只在接手老项目、不方便重新编译的情况下才会考虑它。4. 五个常见坑和排查技巧实录4.1 配置了转发但页面还是空白这个是我见过最多的“假成功”案例。配置完转发后刷新 404 是没了但页面白屏一片打开浏览器控制台还能看到一堆 JS 加载失败。这通常不是转发规则的问题而是前端资源路径问题。前面提过的base配置如果没统一index.html里引用的 JS/CSS 路径在服务器上找不到。排查方法是打开控制台看Network看到底是哪个文件 404 了。如果是/dashboard/assets/index-xxx.js这种路径 404基本可以断定是base配错了改成/或者和部署路径一致的值重新打包即可。4.2 静态资源也被错误转发如果配置不当用/**直接兜底很容易把/assets/index.css这类请求也转入index.html。此时页面会加载出 HTML 内容但样式全丢非常隐蔽因为浏览器不会报 404只是渲染效果错乱。所以我强调用[^\\.]*这种正则来排除带点号的路径。另外注意API 请求要单独处理。如果你的 Controller 有RequestMapping(/api)转发规则不影响它因为 Controller 的映射优先级高于 ViewController但你的其它动态接口如果路径不带/api就可能被 ViewController 拦截出现“接口返回 HTML 而不是 JSON”的怪异现象。建议后端所有接口统一加/api前缀既利于前端代理也便于后端区分。4.3 配置的字符串匹配规则只对一级路由生效有些人在网上复制了一段只配置一级路由的代码形如registry.addViewController(/{path})结果在/dashboard/profile这种二级路由下刷新依然 404。这不是没配置成功而是匹配范围不够。解决方法是复用我第 3 节提供的两条规则一条匹配一级路径一条匹配多级路径。需要注意Spring 的PathPattern语义和正则表达式有很多细节差异官方推荐的{path}匹配在未见斜杠情况下的行为和预期可能不太一样所以务必以测试结果为准。4.4 打包成 war 包部署在外部 Tomcat 时配置失效如果你的项目是老式 war 包部署在独立 Tomcat 下上面说的WebMvcConfigurer方式通常也适用。但如果你用了 Tomcat RewriteValve 的context.xml需要注意context.xml的放置位置和命名空间。外部 Tomcat 的conf/Catalina/localhost/下需要对应应用名的 xml 文件。这点在开发环境验证时经常被漏掉本地内嵌 Tomcat 跑得好好的丢到测试环境就失效。另外外部 Tomcat 部署时index.html的位置不再是classpath:/static/而是解压后的webapps/ROOT/目录转发到forward:/index.html依然有效但资源路径问题会更多一些。如果你在维护这种项目我建议优先把部署方式升级为 jar 包能从源头上减少许多此类问题。4.5 刷新后出现 404 但服务器日志没有任何异常这个现象特别容易误导人。因为请求是后端 404 返回的但这类静态资源匹配的 404 在 Spring Boot 日志里默认是 INFO 级别甚至完全静默Spring Boot 3.x 中NoResourceFoundException默认不输出堆栈。所以很多人翻日志半天找不到问题误以为是玄学。遇到这种情况不要过度依赖日志直接看三个地方是否配置了 ViewController、前端base是否正确、部署路径是否和base匹配。排错顺序基本是“先浏览器开 Network 看路径再后端看配置类是否生效最后看打包产物”。5. 这条经验还能怎么扩展解决完刷新 404 后我逐步把这类问题抽象出一套通用的“静态资源兜底”思维。其实在前后端分离架构里类似的问题不止出现在刷新场景还有几个与之关联的高频场景前端路由懒加载 chunk 404用户在一个 SPA 页面停留很久后点击跳转此时加载对应的异步组件 chunk如果后端的静态资源文件做了版本清理或路径变更就会 404。这一般是因为增量发布时旧 chunk 文件被删了或者 CDN 缓存和最新产物不一致。解决思路是给构建产物加上 hash 戳Vite 默认行为并避免手动改产物文件名。多级嵌套路由刷新比如/org/123/user/profile这种路径在配置里明显比普通场景复杂。我给出的多级兜底规则对嵌套层级数不敏感/**/{path:[^\\.]*}所以和 Vue Router 嵌套路由组合起来效果很好。不同部署环境下路径不一致开发环境用 Vite dev server生产环境挂到/和挂到子路径的配置各不相同。我的经验是不要在代码里硬编码路径尽量使用import.meta.env.BASE_URL统一处理。另外说说状态码优化。虽然兜底正确时我们返回的是index.html且状态码为 200但如果你希望 SEO 层面的 404 状态码能正确暴露可以让后端返回 404 的同时携带index内容。比如前端路由里配置一个专门的 404 页面当用户访问不存在的前端路由时渲染这个页面组件这时状态码从后端角度看依然是 200但用户看到了 404 页面。现在越来越多团队采用这种“前端透明 404”策略既保证了 SPA 体验也满足了内容展示需求。从维护角度看如果团队人多建议把这类配置抽成一个独立的配置类加上注释说明注释里写清楚“不要改成正则以外的匹配方式”之类的警告。这算是一个维护上的小嘱咐。我经手过最头疼的一个项目就是前人写了一个/**兜底结果前端打包后资源路径全被转发了一遍排查了很久才反应过来。配置类上留个注释能帮后面接手的人少走不少弯路。最后再分享一个部署之后我自己的检查习惯每次部署完我会手动在浏览器里打开两到三个深层路由地址然后按 F5 刷新确认页面正常。同时也会在地址栏访问一个完全不存在的路径比如/foo/bar/nonexist确认它至少返回的是index.html而不是后端错误页。这两步走完我才敢放心地说“你这个部署没问题”。这个习惯帮我挡掉过很多次低级失误也顺便推荐给你。