基于Vite+TS的React Router项目部署Github Pages后路由404问题

问题原因 #

本地开发环境中，Vite的dev服务器会将所有路由请求转发到index.html，由React Router接管路由逻辑；但Github Pages是静态文件服务器，当你直接访问/shopping-cart/products这类路径时，服务器会尝试寻找对应目录下的文件，而这类文件实际不存在，所以返回404。

解决方案 #

方案一：使用HashRouter（最简单直接） #

HashRouter会将路由信息放在URL的#之后，静态服务器不会解析#后面的内容，所有路由逻辑由React处理：

1. 修改main.tsx，替换路由组件：

import { HashRouter } from "react-router-dom";

ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
  <React.StrictMode>
    <HashRouter>
      <App />
    </HashRouter>
  </React.StrictMode>
);

2. 修改App.tsx中的路由路径，去掉冗余的shopping-cart前缀：

<Routes>
  <Route path="/" element={<Main />} />
  <Route path="/products" element={<Products setCartItems={setCartItems} />} />
  <Route path="/contact" element={<Contact />} />
</Routes>

3. 重新执行npm run build，再部署到Github Pages即可。此时URL会变为类似https://xxx.github.io/shopping-cart/#/products的格式，不会触发服务器的文件查找。

方案二：保留BrowserRouter，配置404重定向 #

如果不想URL带#，可以通过配置404页面让服务器重定向到index.html：

1. 调整App.tsx的路由路径，与Vite的base配置匹配：

<Routes>
  <Route path="/" element={<Main />} /> {/* 对应base: '/shopping-cart/'的根路径 */}
  <Route path="/products" element={<Products setCartItems={setCartItems} />} />
  <Route path="/contact" element={<Contact />} />
</Routes>

2. 在项目的public文件夹下创建404.html，内容完全复制index.html的代码。这样当服务器找不到对应路径时，会返回404.html，而该页面能加载React应用，由React Router正确渲染对应路由。

3. 重新构建并部署，此时直接访问/shopping-cart/products这类路径，服务器返回404.html后，React会接管路由并显示正确页面。

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