GitHub Pages部署React应用仅显示首页、子页面404报错如何解决？

数据老陈

2026-10-1

问题原因

这是单页应用客户端路由在GitHub Pages部署的典型问题：单页应用使用BrowserRouter模式时，依赖服务端配置将所有路由请求重定向到入口index.html，而GitHub Pages仅提供静态文件托管能力，无对应服务端配置，直接访问子路由路径时，服务端会尝试查找对应路径的静态文件，找不到就返回404错误。

解决方案

方案1：替换为HashRouter（改造成本最低）
如果你使用react-router等路由库，将原有的BrowserRouter替换为HashRouter即可：
原有引入代码：
```
import { BrowserRouter as Router } from 'react-router-dom'
```
替换为：
```
import { HashRouter as Router } from 'react-router-dom'
```
该方案会给路径增加#标识，所有路由逻辑都在首页路径下执行，不需要服务端额外支持，改完重新打包部署即可生效。
方案2：添加404兜底文件
在项目public目录下创建404.html文件，将index.html的全部内容复制到404.html中，同时可以在public目录下新增一个空的.nojekyll文件，避免GitHub Pages的Jekyll解析逻辑忽略下划线开头的静态资源。改完重新打包部署后，所有找不到对应路径的请求都会返回404.html的内容，也就是你的应用入口，客户端路由就能正常匹配路径。
方案3：配置重定向规则
在项目public目录下创建_redirects文件，写入以下内容：
```
/* /index.html 200
```
打包后该文件会被自动放到输出根目录，GitHub Pages会识别该规则，将所有路径请求都重定向到index.html走客户端路由逻辑，该方案可以保留无#的干净路径格式。