非SSR React SPA如何实现邮件带参链接跳转及Spring网关适配

完全可以基于现有SPA架构实现该需求，无需改造为SSR，核心需要解决两个层面的问题：Spring Cloud Gateway对SPA前端路由的透传兜底、React端的路由匹配与URL参数读取。

当前配置的核心问题 #

现有网关规则仅匹配/index.html、/static/**两类请求路径，当用户直接访问/email、/messages这类前端路由路径时，网关无匹配的转发规则，会直接返回404，无法正常加载React应用。

第一步：调整Spring Cloud Gateway路由规则 #

配置逻辑 #

所有SPA前端路由的请求，最终都需要加载React应用的入口文件index.html，因此需要新增兜底转发规则：将所有前端自定义路由路径的请求，统一重写到React服务的/index.html入口，同时完整保留浏览器地址栏的原始路径、查询参数，供React路由解析。

修改后的路由代码 #

public RouteLocator customRouteLocator(RouteLocatorBuilder builder) {
    return builder.routes()
            // 保留原有静态资源、入口文件的转发规则
            .route("react-app", r -> r.path("/index.html")
                    .uri("http://example-react:9001"))
            .route("react-static-files", r -> r.path("/static/**")
                    .uri("http://example-react:9001"))
            // 新增：SPA前端路由兜底规则
            .route("spa-frontend-routes", r -> r.path("/email", "/messages/**")
                    // *关键配置*：重写所有前端路由请求到React应用的index.html入口，不修改地址栏路径和查询参数
                    .filters(f -> f.rewritePath("/(?<frontendPath>.*)", "/index.html"))
                    .uri("http://example-react:9001"))
            .build();
}

关键注意事项 #

路由匹配顺序要求：Spring Cloud Gateway的路由匹配为自上而下的顺序执行，更具体的路径规则（如静态资源、接口路径）必须放在通用兜底规则之前，避免静态资源被错误重写到index.html入口，导致页面样式、脚本加载失败。

• Spring Cloud Gateway默认会完整透传查询参数，无需额外配置即可让React端读到URL上的id等参数
• 如果希望后续新增前端路由时无需反复修改网关配置，可以将兜底规则调整为全局匹配模式，排除静态资源、后端接口路径即可：

// 全局兜底配置示例，无需每次新增前端路由都修改网关规则
.route("spa-frontend-routes", r -> r
    .path("/**")
    // 排除无需走SPA逻辑的路径
    .and().not(p -> p.path("/static/**", "/index.html", "/api/**"))
    .filters(f -> f.rewritePath("/(?<originalPath>.*)", "/index.html"))
    .uri("http://example-react:9001")
)

第二步：React端路由与参数读取实现 #

配置要求 #

React端使用BrowserRouter模式（和邮件链接的无哈希路径格式匹配，避免带#的链接被邮件客户端过滤截断），路由路径和网关暴露的实际路径完全对齐，确保加载完入口文件后能匹配到对应组件。

示例代码 #

import { createBrowserRouter, RouterProvider, useSearchParams } from 'react-router-dom';
import Home from './pages/Home';
import Email from './pages/Email';
import Messages from './pages/Messages';

// 路由路径与网关暴露的路径一一对应
const router = createBrowserRouter([
  { path: '/', element: <Home /> },
  { path: '/email', element: <Email /> },
  { path: '/messages', element: <Messages /> }
]);

// Messages组件中读取URL上的id参数
function Messages() {
  const [searchParams] = useSearchParams();
  const targetId = searchParams.get('id'); // 直接获取链接中携带的id查询参数
  // 基于读取到的id执行业务逻辑
  return <div>当前加载的消息ID：{targetId}</div>
}

// 挂载路由
ReactDOM.createRoot(document.getElementById('root')).render(
  <RouterProvider router={router} />
);

完整加载流程验证 #

当用户点击邮件中的http://example.com/react/messages?id=123链接时，流程为：

1. 浏览器携带完整路径和参数发起请求
2. 网关匹配到SPA兜底规则，重写请求为React服务的/index.html路径，透传原始查询参数
3. 浏览器加载入口HTML、React的静态JS资源
4. React路由读取当前地址栏的路径，匹配到Messages组件
5. 组件通过路由钩子读取URL上的id参数，执行后续业务逻辑

内容的提问来源于stack exchange，提问作者Michał Artur Marciniak