如何修复GitHub Pages与React带参数路由的404错误

问题本质 #

React使用的是客户端路由（基于BrowserRouter），而GitHub Pages是静态文件托管服务。当你直接访问github.io/solutions/1这类带参数的路由时，服务器会尝试寻找对应路径的物理文件（比如/solutions/1.html），找不到就返回404，不会自动返回React的入口文件index.html，导致客户端路由无法解析参数并渲染对应页面。

解决方案 #

方法一：用HashRouter替代BrowserRouter（快速简单）

将路由根组件从BrowserRouter换成HashRouter，所有路由会带上#前缀（比如github.io/#/solutions/1）。这种方式下，所有请求都会指向根目录的index.html，服务器不会返回404，客户端路由能正常解析参数。

修改代码示例：

// 替换导入
// import { BrowserRouter } from 'react-router-dom';
import { HashRouter } from 'react-router-dom';

// 包裹路由的根组件
ReactDOM.createRoot(document.getElementById('root')!).render(
  <HashRouter>
    <ContentRoutes />
  </HashRouter>
);

• 优点：零额外配置，快速生效；缺点：URL会多一个#，美观性稍差。

方法二：添加404重定向规则（推荐，保持URL美观）

利用GitHub Pages的404页面特性，让所有404请求重定向到index.html，同时保留原路由信息，由React路由解析。

1. 在项目public目录下创建404.html文件，内容如下：

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <title>Redirecting...</title>
  <script>
    // 获取当前请求的完整路径和参数
    const fullPath = window.location.pathname + window.location.search;
    // 重定向到index.html，携带原路径参数
    window.location.href = '/index.html?path=' + encodeURIComponent(fullPath);
  </script>
</head>
<body>
  <p>Redirecting to your requested page...</p>
</body>
</html>

2. 在React入口文件（如index.tsx）中添加初始化逻辑，处理重定向过来的路径：

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

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

  useEffect(() => {
    const searchParams = new URLSearchParams(window.location.search);
    const redirectPath = searchParams.get('path');
    
    if (redirectPath) {
      // 导航到原请求的路径
      navigate(decodeURIComponent(redirectPath));
      // 清理URL中的临时参数，保持地址栏干净
      window.history.replaceState({}, document.title, window.location.pathname);
    }
  }, [navigate]);

  return <ContentRoutes />;
}

3. 确保路由仍使用BrowserRouter，重新构建并部署项目到GitHub Pages即可。

• 优点：URL保持原生风格，无额外前缀；缺点：需要添加配置文件和初始化代码。

额外注意事项 #

如果你的项目用create-react-app创建，部署前务必在package.json中添加homepage字段，确保资源路径正确：

"homepage": "https://your-username.github.io/your-repo-name"

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