React项目部署GitHub Pages出现404 Not Found错误的解决方法

核心原因 #

GitHub Pages是静态文件托管服务，当使用React Router的BrowserRouter时，直接访问子路由（比如/profile）或刷新页面，服务器会尝试寻找对应路径的静态文件，但React的SPA路由是客户端处理的，服务器没有对应文件就会返回404。Netlify默认配置了重写规则，会把所有请求指向index.html，所以不会出现这个问题。

解决方案 #

方案1：改用HashRouter #

这是最简单直接的方法，HashRouter的路由基于URL的hash部分（比如https://tevfik94.github.io/social_app/#/profile），这部分不会发送到服务器，GitHub Pages能正确返回index.html，由客户端路由处理逻辑。

修改路由代码：

// 导入HashRouter替代BrowserRouter
import { HashRouter as Router, Routes, Route } from 'react-router-dom';

function App() {
  return (
    <Router>
      <Routes>
        {/* 你的原有路由配置 */}
        <Route path="/" element={<Home />} />
        <Route path="/profile" element={<Profile />} />
        {/* 按提示添加errorElement优化报错体验 */}
        <Route errorElement={<NotFoundPage />} />
      </Routes>
    </Router>
  );
}

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

如果不想用带hash的路径，可通过以下步骤配置：

1. 在项目根目录的package.json中添加homepage字段：

"homepage": "https://tevfik94.github.io/social_app/"

2. 在public文件夹下创建404.html，完全复制public/index.html的内容。
3. 确保已安装gh-pages包，然后在package.json的scripts中添加部署命令：

"scripts": {
  "predeploy": "npm run build",
  "deploy": "gh-pages -d build"
}

当用户访问不存在的路径时，GitHub Pages会返回404.html，这个文件和index.html一致，客户端路由就能正常接管并渲染对应页面。

额外优化：自定义errorElement #

按照报错提示添加自定义404页面，提升用户体验：

function NotFoundPage() {
  return (
    <div style={{ textAlign: 'center', padding: '50px' }}>
      <h1>404 - 页面未找到</h1>
      <p>你访问的页面不存在</p>
      <Link to="/">返回首页</Link>
    </div>
  );
}

然后在路由配置中引入这个组件即可。

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