React Router 6.22.3仅生产环境路由不渲染问题排查

问题 #

React Router 6.22.3仅在生产环境下路由无法渲染，开发环境完全正常：

• 开发环境可正常访问路由：
  • http://localhost:5173/
  • http://localhost:5173/#/about
• 生产环境部署在https://my-domain/audio-ui/下，对应路由（https://my-domain/audio-ui/、https://my-domain/audio-ui/#/about）无法工作
• 构建命令：tsc && vite build --base=/audio-ui/，需使用/audio-ui子路径
• 同构建方式但未使用React-Router-DOM的项目可正常运行

项目核心路由代码（main.tsx）：

// import React from 'react';
import ReactDOM from 'react-dom/client';
import Dashboard from './Dashboard.tsx';
import '@fontsource/roboto/300.css';
import '@fontsource/roboto/400.css';
import '@fontsource/roboto/500.css';
import '@fontsource/roboto/700.css';
// import { CssBaseline, ThemeProvider, createTheme } from '@mui/material';
import { RouterProvider, createHashRouter } from 'react-router-dom';
import Volume from './Volume.tsx';
import About from './About.tsx';
import ErrorPage from './ErrorPage.tsx';
import Root from './Root.tsx';

const router = createHashRouter(
  [
    {
      path: '/',
      element: <Root />,
      errorElement: <ErrorPage />,
      children: [
        {
          path: '',
          element: <Dashboard />,
        },
        {
          path: 'volume',
          element: <Volume />,
        },
        {
          path: 'about',
          element: <About />,
        },
      ],
    },
  ],
  { basename: import.meta.env.BASE_URL }
);

ReactDOM.createRoot(document.getElementById('root')!).render(
  <RouterProvider router={router} />
);

原因分析 #

使用createHashRouter时，basename会被自动追加到hash路由的路径前。生产环境下import.meta.env.BASE_URL的值为/audio-ui/，这会让实际生效的hash路由路径变成#/audio-ui/about，但你访问的是#/about，导致路由规则不匹配，组件无法渲染。

另外，Hash路由的特性是完全由前端控制路径，无需依赖basename适配服务器子路径——服务器只需要返回index.html，hash部分不会被服务器解析，所以这里的basename配置属于冗余且错误的设置。

修复方案 #

方案1：移除HashRouter的basename配置（推荐） #

直接删除createHashRouter的basename选项即可，Hash路由不需要该配置来适配子路径：

const router = createHashRouter(
  [
    // 原路由配置保持不变
  ]
  // 移除 { basename: import.meta.env.BASE_URL } 这一行
);

方案2：同步调整访问路径（不推荐） #

若因特殊需求必须保留basename，需将访问路径的hash部分加上basename前缀，比如访问https://my-domain/audio-ui/#/audio-ui/about，但这种方式不符合常规使用习惯，不建议采用。

额外注意：确保生产环境服务器配置正确，对于/audio-ui/下的所有请求，都返回项目的index.html文件（Hash路由通常不需要此配置，但如果存在资源加载问题时需要检查）。

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