Vite搭配react-router-dom构建后仅根路径/路由可访问问题咨询

• 服务端History路由回退规则缺失（占这类问题的90%以上）：Vite开发模式自带的dev server默认内置了History API路由的回退逻辑，无论访问什么路径，都会返回入口index.html文件，因此开发环境下路由跳转、直接访问子路径都能正常加载React应用。但打包产物部署到静态服务（Nginx、Apache、静态文件服务、云存储静态托管等）时，服务端默认只会对根路径/的请求返回index.html，直接访问子路由路径（比如/about）时，服务端会去查找对应路径下的实体文件，找不到就直接返回404，React应用根本无法加载，路由自然失效。
• react-router-dom版本适配错误：如果使用v6及以上版本的react-router-dom，框架默认所有路由都是精确匹配，根本不存在exact属性，手动写exact虽然不会直接抛错，但如果混用v5/v6的路由组件写法，打包时Tree Shaking可能误删路由匹配逻辑，导致子路由失效。
• Vite基础路径配置错误：如果项目不是部署在域名根目录，而是挂载在子路径下，但是vite.config.js中没有配置对应base参数，打包后静态资源路径引用错误，子路由加载时会因为资源404出现白屏。

1. 配置服务端History路由回退规则 #

根据实际部署的服务选择对应配置即可，不需要修改前端业务代码：

• Nginx部署：在对应的server配置块中添加try_files规则，将所有非静态文件请求统一指向入口index.html

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

• Apache部署：在打包生成的dist目录根路径新建.htaccess文件，写入重定向规则

<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /
  RewriteRule ^index\.html$ - [L]
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule . /index.html [L]
</IfModule>

• 本地预览打包产物：启动preview服务时加上回退参数即可，命令为vite preview --host --historyApiFallback，如果本地预览时所有路由都能正常访问，即可确定问题是部署环境的回退规则缺失。
• Vercel/Netlify等前端托管平台部署：按照平台要求添加重定向规则即可，比如Netlify只需在项目public目录下新建_redirects文件，写入/* /index.html 200。
• 不想配置服务端规则的快速方案：直接将路由的BrowserRouter替换为HashRouter，路由会基于URL的hash部分（#后面的内容）实现匹配，所有请求都会默认返回根路径的index.html，不需要额外配置服务端，缺点是URL带#标识，美观度不足，对SEO不友好。

2. 修正react-router-dom适配问题 #

• 如果使用react-router-dom v6.x版本：删除所有Route组件上的exact属性，统一使用v6规范的路由写法，参考示例：

import { BrowserRouter, Routes, Route } from 'react-router-dom'
import Home from './pages/Home'
import About from './pages/About'

function App() {
  return (
    <BrowserRouter>
      <Routes>
        <Route path="/" element={<Home />} />
        <Route path="/about" element={<About />} />
      </Routes>
    </BrowserRouter>
  )
}

• 如果使用react-router-dom v5.x版本：注意exact属性只需要加在无嵌套的精确匹配路由上，不要给父级路由添加exact导致嵌套子路由无法匹配，同时不要混用v6版本的路由组件。

3. 修正Vite基础路径配置 #

如果项目部署在域名的子路径下（例如https://your-domain.com/react-app/），需要在vite.config.js中配置对应的base值：

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  base: '/react-app/', // 替换为实际部署的子路径，部署在根路径则填'/'
})

排查小技巧：先本地用带historyApiFallback参数的preview命令启动打包产物，如果所有路由访问正常，就不用排查前端代码问题，直接检查部署服务的回退配置即可。

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