React项目部署GitHub Pages后路由异常问题求助

核心问题原因 #

GitHub Pages部署在子路径（user.github.io/reponame）时，React Router默认以根域名作为路由基准，忽略package.json中homepage配置的子路径，导致路由匹配、跳转路径及嵌套路由全部出现异常。

解决方案（无需硬编码） #

1. 动态配置路由基准路径 #

利用React Router的basename属性，自动从homepage字段提取基准路径，完全不用硬写仓库名：

import { BrowserRouter as Router, Routes, Route, Link } from 'react-router-dom';
// 自动读取package.json中homepage的子路径部分，比如homepage为"https://user.github.io/reponame"时，basename值为"/reponame"
const basename = process.env.PUBLIC_URL;

function App() {
  return (
    <Router basename={basename}>
      <nav>
        <Link to="/">首页</Link>
        <Link to="/about">关于</Link>
      </nav>
      <Routes>
        <Route path="/" element={<Home />} />
        <Route path="/about" element={<About />} />
        {/* 嵌套路由直接用相对路径，无需额外处理 */}
        <Route path="/posts" element={<Posts />}>
          <Route path=":id" element={<PostDetail />} />
        </Route>
      </Routes>
    </Router>
  );
}

2. 修复根路径刷新404问题 #

在项目根目录的public文件夹下创建404.html，内容完全复制public/index.html的代码。GitHub Pages在找不到对应路径时会加载该文件，让React Router接管路由匹配逻辑，解决刷新404的问题。

3. 验证基础配置 #

确保package.json的homepage配置正确：

{
  "homepage": "https://user.github.io/reponame"
}

部署脚本使用官方推荐配置（需先安装gh-pages依赖）：

npm install --save-dev gh-pages

在package.json的scripts中添加：

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

执行npm run deploy完成部署。

关键注意事项 #

• 所有Link的to属性使用相对路径（如to="/"、to="/about"），不要手动添加子路径前缀，basename会自动处理
• 嵌套路由直接写相对父路由的路径，无需考虑基准路径
• 不要手动修改%PUBLIC_URL%，process.env.PUBLIC_URL已封装该逻辑

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