Vite+React部署GitHub Pages后刷新路由遇404问题求助

问题根源 #

GitHub Pages作为静态托管服务，处理路由请求时会优先查找对应物理路径的文件。而你的React应用是单页应用（SPA），所有路由都是前端通过TanStack Router接管的，不存在/portfolio/about这类物理文件，因此刷新或直接访问子路由时会返回404。

解决步骤 #

1. 添加404.html文件 #

在项目的public目录下创建404.html，将public/index.html的内容完全复制进去。GitHub Pages在找不到请求路径对应的文件时，会自动加载404.html，而这个文件和主入口文件一致，能让TanStack Router正常接管路由逻辑。

2. 配置TanStack Router的basename #

确保TanStack Router的basename与Vite配置中的base值保持一致（即/portfolio/）：

• 若使用自动生成的基于文件的路由，在RouterProvider中传入routerOptions：

import { RouterProvider, router } from './__generated__/router';

function App() {
  return (
    <RouterProvider 
      router={router} 
      routerOptions={{ basename: '/portfolio/' }} 
    />
  );
}

• 若手动创建路由，在createRouter时指定basename：

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

const router = createRouter({
  routes: [...], // 你的路由定义
  basename: '/portfolio/',
});

3. 重新部署应用 #

将上述修改提交到main分支，触发GitHub Actions重新构建并部署。部署完成后，刷新或直接访问子路由即可正常加载页面。

验证方法 #

部署完成后，尝试直接访问https://samir0ps.github.io/portfolio/about，或者在应用内导航到该路由后刷新页面，确认页面能正常加载，无404错误。

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