Spring Boot整合React时路由刷新报Whitelabel错误如何解决？

这不是路由优先级的问题，本质是前后端路由的工作逻辑差异：

• 用react-router-dom的Link组件跳转时，不会触发整页刷新，路径变化完全由浏览器端JS拦截处理，所以能正常匹配React定义的路由
• 直接输入URL访问、或者手动刷新页面时，浏览器会把当前路径作为请求直接发给Spring Boot后端。后端默认只匹配@Controller/@RestController定义的接口映射，找不到对应路径就返回Whitelabel 404错误页，请求根本不会交给前端React路由处理。

核心逻辑很简单：后端把所有非API类的请求，统一转发到React打包生成的入口文件index.html，后续路径匹配完全交给前端React Router处理即可。

方案1：自定义MVC转发规则（推荐，无副作用） #

在Spring Boot项目中新增一个Web配置类，分两类规则处理请求：

1. 后端接口路径（比如统一前缀为/api/**的接口）、静态资源（js、css、图片等）走默认处理逻辑
2. 其余所有GET请求，全部转发到静态目录下的index.html
   参考代码：

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ViewControllerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebRouteConfig implements WebMvcConfigurer {
    @Override
    public void addViewControllers(ViewControllerRegistry registry) {
        // 匹配单层级前端路由，比如/login、/cart、/account
        registry.addViewController("/{path:[\\w\\-]+}")
                .setViewName("forward:/index.html");
        // 匹配多层级带参数的前端路由，比如/item/123、/categories/2/items/search/phone
        registry.addViewController("/{prefix:^(?!api$).*$}/**/{subPath:[\\w\\-]+}")
                .setViewName("forward:/index.html");
    }
}

如果你的后端接口没有统一加/api前缀，调整正则规则把实际接口路径排除即可，不会影响接口正常响应。

方案2：复用错误页转发（配置量最小） #

Spring Boot默认所有404请求都会转发到/error路径，可以直接实现ErrorController把对应请求转发回index.html：

import org.springframework.boot.web.servlet.error.ErrorController;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;

import javax.servlet.http.HttpServletRequest;

@Controller
public class ForwardIndexController implements ErrorController {
    @RequestMapping("/error")
    public String handleError(HttpServletRequest request) {
        // 接口请求直接返回错误响应，不转发到前端
        if (request.getRequestURI().startsWith("/api/")) {
            throw new RuntimeException("接口请求异常");
        }
        return "forward:/index.html";
    }
}

注意：这个方案一定要加接口路径判断，否则后端接口抛出的4xx、5xx错误都会被转发成前端页面，前端拿不到接口的错误状态和返回内容。

• 确认maven-frontend-plugin打包配置正确：React执行npm run build生成的index.html、static静态资源目录，要输出到Spring Boot默认的静态资源路径下（通常是target/classes/static/），否则后端转发时找不到index.html会报500错误
• 如果React Router配置了basename，不需要修改后端转发规则，只要请求能正常返回index.html，前端会自动匹配对应路由
• 配置完成后重启服务，直接访问/login、刷新/cart这类路径就不会再出现Whitelabel错误页，对应React组件可以正常加载。

内容的提问来源于stack exchange，提问作者Moris