React项目部署gh-pages后非主页刷新出现404问题求助

这个问题本质是gh-pages作为静态文件服务器，刷新非主页路径时会直接去查找对应静态文件，但React是单页应用，所有路由都是前端处理的，服务器根本没有这些文件，所以返回404。下面给几个靠谱的解决办法：

方法一：改用HashRouter（最简单） #

把项目里的BrowserRouter换成HashRouter，这样URL会带上#，刷新时服务器只会加载根目录的index.html，前端路由会通过#后面的内容处理路径，不会触发服务器的文件查找。

示例代码：

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

function App() {
  return (
    <Router>
      <Routes>
        <Route path="/" element={<Home />} />
        <Route path="/about" element={<About />} />
        {/* 其他路由 */}
      </Routes>
    </Router>
  );
}

优点是零配置，缺点是URL会多一个#，对SEO有一点点影响，但个人项目基本可以忽略。

方法二：配置404.html实现无#路由跳转 #

如果不想用HashRouter，可以通过正确配置404.html来实现。之前的404.html和脚本没起作用，是因为路径处理逻辑不对，试试下面的配置：

1. 创建/修改404.html #

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>Redirecting to App</title>
  <script>
    // 捕获当前完整路径（含查询参数、哈希）
    const fullPath = window.location.pathname + window.location.search + window.location.hash;
    // 重定向到index.html，把路径作为redirect参数传递
    // 注意替换成你的仓库base路径，用户站点（username.github.io）直接用 '/'
    window.location.replace('/your-repo-name/?redirect=' + encodeURIComponent(fullPath));
  </script>
</head>
<body>
  Loading...
</body>
</html>

2. 在React应用中处理redirect参数 #

在App组件里，初始化时检查URL的redirect参数，跳转到对应的路由：

import { useEffect } from 'react';
import { useNavigate } from 'react-router-dom';

function App() {
  const navigate = useNavigate();

  useEffect(() => {
    const params = new URLSearchParams(window.location.search);
    const redirectPath = params.get('redirect');
    if (redirectPath) {
      // 跳转到目标路径，并清除URL上的redirect参数
      navigate(decodeURIComponent(redirectPath), { replace: true });
    }
  }, [navigate]);

  return (
    <Routes>
      {/* 你的路由配置 */}
      <Route path="/" element={<Home />} />
      <Route path="/about" element={<About />} />
    </Routes>
  );
}

3. 确保package.json配置正确 #

必须在package.json里设置homepage，否则资源路径和路由会出错：

// 仓库站点
"homepage": "https://your-username.github.io/your-repo-name"
// 个人用户站点
"homepage": "https://your-username.github.io"

为什么你之前的代码无效？ #

你那段脚本的路径分割逻辑是硬编码的pathSegmentsToKeep = 1，如果你的仓库有二级路径（比如username.github.io/repo-name），这个值应该是2，不然会把路径切错，导致跳转后的URL无法被React路由识别。而且脚本没有把路径传递给React路由的逻辑，只是做了URL替换，所以刷新后还是找不到对应页面。

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