ReactJS部署Github Pages后直接输入URL访问出现404问题求助

问题原因 #

本地开发时，React的开发服务器会把所有路由请求转发到index.html，让前端路由处理逻辑。但Github Pages是静态文件服务器，直接访问子路由（比如/summary）时，服务器会尝试寻找对应路径的静态文件，找不到就返回404——而单页应用的所有路由逻辑都封装在index.html里。

解决步骤 #

1. 确认package.json配置

先确保package.json里已设置正确的homepage字段，值对应你的Github Pages项目地址：

"homepage": "https://hayatshin.github.io/todaychungchun-admin/"

同时检查scripts中的部署命令（未配置的话补充）：

"scripts": {
  // ...其他原有脚本
  "predeploy": "npm run build",
  "deploy": "gh-pages -d build"
}

2. 创建404.html文件

在项目的public文件夹下，复制一份index.html并重命名为404.html。当Github Pages找不到对应路径的文件时，会返回这个404.html，此时React的前端路由就能接管请求，解析对应路由并渲染页面。

3. 重新部署项目

运行部署命令重新推送到Github Pages：

npm run deploy

备选方案：改用HashRouter #

如果不想额外配置404.html，可以把BrowserRouter换成HashRouter，路由会带上#（比如https://hayatshin.github.io/todaychungchun-admin/#/summary），这种方式下所有请求都会指向根路径的index.html，不会触发服务器404。修改路由配置：

import { HashRouter as Router, Routes, Route } from 'react-router-dom';

// 后续保持原路由结构即可
<Router basename={process.env.PUBLIC_URL}>
  <Routes>
    {/* 你的路由配置 */}
  </Routes>
</Router>

缺点是URL会多一个#，但配置更简洁。

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