React Vite部署Github Pages多页面导航404问题求助

GitHub Pages 是静态文件托管服务，当你通过 window.location.pathname 跳转至 /about 这类子路径时，浏览器会向服务器发起新请求，尝试查找对应路径下的静态 HTML 文件（比如 about.html）。但你的 Vite 项目默认是单页应用（SPA），打包后只有根目录的 index.html，因此服务器返回 404 错误。

方案1：使用 React Router（推荐） #

直接用成熟的路由库能彻底解决 SPA 路由在静态托管平台的适配问题，步骤如下：

1. 安装依赖：

npm install react-router-dom

2. 改用 HashRouter 替代原生路径跳转（Hash 模式的路由不会触发服务器请求，所有路由逻辑在前端处理）：

import { HashRouter, Routes, Route, Link } from 'react-router-dom';
import Home from './pages/Home';
import About from './pages/About';

function App() {
  return (
    <HashRouter>
      {/* 导航栏用 Link 组件实现无跳转刷新 */}
      <nav>
        <Link to="/">首页</Link>
        <Link to="/about">关于我</Link>
      </nav>
      {/* 路由配置 */}
      <Routes>
        <Route path="/" element={<Home />} />
        <Route path="/about" element={<About />} />
      </Routes>
    </HashRouter>
  );
}

3. 正常打包部署即可，无需额外配置 GitHub Pages。

方案2：不使用路由库，改造现有逻辑 #

如果不想引入路由库，可以通过 Hash 模式和 404 页面兜底来解决：

1. 修改跳转逻辑，改用 window.location.hash 实现前端路由：

// 导航点击事件
const navigate = (path) => {
  window.location.hash = path;
};

// 监听 Hash 变化，切换对应组件
useEffect(() => {
  const handleHashChange = () => {
    const currentPath = window.location.hash.slice(1) || '/';
    // 根据 currentPath 渲染对应页面组件
  };
  window.addEventListener('hashchange', handleHashChange);
  handleHashChange(); // 初始化时执行一次
  return () => window.removeEventListener('hashchange', handleHashChange);
}, []);

2. 在仓库根目录创建 404.html，内容完全复制 index.html。当用户直接访问子路径触发 404 时，GitHub Pages 会返回这个文件，前端就能通过 Hash 逻辑接管路由。

关于 base 和 homepage 配置的说明 #

如果你部署的是 username.github.io 根域名仓库，vite.config.ts 里的 base 只需设为 '/'，无需配置 package.json 的 homepage。之前配置无效大概率是因为未配合 404 页面或路由模式的改造，单纯配置 base 无法解决 SPA 路由的服务器适配问题。

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