Vite多页面+Tanstack Router刷新路由异常问题咨询

问题描述 #

我正在开发一个需要创建3个HTML文件的项目，这些文件共享同一JS源码。核心原因是每个HTML需要对应不同的manifest文件，以此实现拥有不同主题和图标的PWA应用。我使用Vite和Tanstack Router搭建项目，并遵循Vite官方多页面应用构建指南创建了3个独立HTML文件。项目能正常运行，但当导航至Tanstack Router的内部路由后刷新浏览器，服务器会判定用户处于根页面而非当前内部路由。

问题根源 #

Vite开发服务器默认仅将所有404请求重定向到根目录的index.html，但多页面场景下，不同入口的内部路由需要对应到各自的HTML文件，默认配置无法区分不同入口的路由归属，导致刷新时错误跳转到根页面。

解决方案 #

1. 配置Vite开发服务器的路由 fallback #

在vite.config.js中通过server.historyApiFallback.rewrites自定义路由映射，确保每个入口的内部路由刷新时指向对应的HTML文件：

import { defineConfig } from 'vite'

export default defineConfig({
  server: {
    historyApiFallback: {
      rewrites: [
        // 匹配app2下的所有路由，刷新时指向app2.html
        { from: /^\/app2\/.*/, to: '/app2.html' },
        // 匹配app3下的所有路由，刷新时指向app3.html
        { from: /^\/app3\/.*/, to: '/app3.html' },
        // 默认路由指向index.html
        { from: /./, to: '/index.html' },
      ],
    },
  },
  // 确保多页面入口配置正确（若未配置需添加）
  build: {
    rollupOptions: {
      input: {
        main: './index.html',
        app2: './app2.html',
        app3: './app3.html',
      },
    },
  },
})

2. 给Tanstack Router路由添加对应入口前缀 #

每个入口的路由需添加专属前缀，确保和Vite的rewrite规则匹配。比如app2的路由配置：

import { createRouter, createRouteConfig } from '@tanstack/react-router'

const routeConfig = createRouteConfig([
  {
    path: '/app2',
    children: [
      { path: 'dashboard', component: () => <div>App2 Dashboard</div> },
      { path: 'settings', component: () => <div>App2 Settings</div> },
    ],
  },
])

export const router = createRouter({ routeConfig })

3. 生产环境部署配置 #

如果部署到生产环境，需要在服务器（如Nginx、Apache）中配置对应的SPA fallback规则，逻辑和开发服务器一致：

• Nginx配置示例：

location /app2/ {
  try_files $uri $uri/ /app2.html;
}
location /app3/ {
  try_files $uri $uri/ /app3.html;
}
location / {
  try_files $uri $uri/ /index.html;
}

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