如何在GitHub Pages部署的React应用中实现多子路由？

核心原因 #

GitHub Pages是静态文件托管服务，直接访问子路由（如/cv/dev）时，服务器会尝试寻找对应路径的静态文件（比如/cv/dev/index.html），但SPA的路由是客户端处理的，移除预渲染后不存在这些文件，因此返回404。

具体解决方案 #

1. 用BrowserRouter的basename统一处理路由前缀 #

替换手动拼接路径的方式，通过basename属性统一管理生产环境的路由前缀，避免手动拼接出错：

修改App.js中的BrowserRouter部分：

<BrowserRouter basename={process.env.NODE_ENV === 'production' ? '/cv' : ''}>
  <Routes>
    <Route path="/" element={<CurriculumVitae domain={EnumDomain.GENERIC}  />} />
    <Route path="/dev" element={<CurriculumVitae domain={EnumDomain.DEV} />} />
    <Route path="/maths" element={<CurriculumVitae domain={EnumDomain.MATHS} />} />
  </Routes> 
</BrowserRouter>

完成后可以直接移除pathBuilder方法，basename会自动为所有路由添加生产环境的/cv前缀。

2. 配置package.json的homepage字段 #

在package.json中添加homepage字段，指定GitHub Pages的部署路径：

"homepage": "https://[githubname].github.io/cv"

或者更简洁的写法（GitHub Pages会自动识别用户名）：

"homepage": "/cv"

该配置会让create-react-app在构建时正确生成静态资源的引用路径。

3. 添加404.html回退页面 #

在项目的public目录下创建404.html文件，内容完全复制index.html的内容。

当GitHub Pages找不到对应路径的静态文件时，会返回这个404.html，此时客户端的React Router会接管URL，正确渲染对应的子页面。

4. 重新构建并部署 #

运行构建命令：

npm run build

将build文件夹中的所有内容部署到GitHub Pages的对应分支（通常是gh-pages分支）。

验证 #

部署完成后，直接访问子路由（如https://[githubname].github.io/cv/dev），应该能正常加载对应的页面，不会再出现404错误。

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