React应用部署GitHub Pages时路由加载异常问题求助

DevOps 小满

2026-8-26

React 项目部署 GitHub Pages 路由故障修复方案

针对部署后首次加载异常、必须点击导航才能正常使用的问题，按以下步骤排查修复，覆盖React Router v6 版本的配置差异：

修正路由组件的basename配置
React Router v6 版本中，直接给底层Router组件传basename不会生效，必须使用你实际采用的上层路由组件传入配置：
如果使用history模式路由，正确写法如下：

import { BrowserRouter, Routes, Route } from 'react-router-dom';

function App() {
  return (
    <BrowserRouter basename={process.env.PUBLIC_URL}>
      <Routes>
        {/* 在此处配置所有页面路由，包括Inicio对应的首页路由 */}
        <Route path="/" element={<Inicio />} />
        {/* 其余业务路由 */}
      </Routes>
    </BrowserRouter>
  )
}

不要硬编码子路径作为basename，通过process.env.PUBLIC_URL读取配置可以避免后续部署路径变更时重复修改代码

确认package.json的homepage字段配置
打开项目根目录的package.json，在最外层配置和部署地址完全匹配的homepage字段，否则process.env.PUBLIC_URL无法正确识别子路径：
```
"homepage": "https://nam3216.github.io/serigrafia/",
```
配置完成后需要重新执行构建命令，才能让路径参数生效。
配置GitHub Pages的404重定向规则
这是配置basename后仍失效的核心原因：GitHub Pages是静态文件服务，直接访问子路由路径时，服务端会查找对应路径下的静态文件，找不到就返回404，不会加载React应用，自然无法触发客户端路由，只有点击应用内导航时才会走前端路由逻辑。
修复步骤：
1. 在项目public目录下新建404.html文件，内容和构建后生成的index.html内容完全一致
2. 在public/index.html的head标签最开头加入路径恢复脚本：
```
<script>
  (function() {
    const redirectPath = sessionStorage.redirect;
    delete sessionStorage.redirect;
    if (redirectPath && redirectPath !== location.href) {
      history.replaceState(null, null, redirectPath);
    }
  })();
</script>
```
1. 在public/404.html的head标签最开头加入重定向脚本：
```
<script>
  (function() {
    sessionStorage.redirect = location.href;
  })();
</script>
<meta http-equiv="refresh" content="0;URL='/serigrafia/'">
```
零配置兼容方案：切换为Hash路由
如果不想维护404重定向逻辑，可以直接将路由模式切换为hash模式，路由路径会自动拼接在#后，GitHub Pages不会识别#后的内容为文件路径，不会触发404问题，配置如下：
```
import { HashRouter, Routes, Route } from 'react-router-dom';

function App() {
  return (
    <HashRouter basename={process.env.PUBLIC_URL}>
      <Routes>
        {/* 所有业务路由配置 */}
      </Routes>
    </HashRouter>
  )
}
```
该方案的缺点是URL会携带#标识，对搜索引擎抓取不友好，适合无SEO需求的内部项目、演示类项目使用
重新构建部署验证
所有配置修改完成后，删除旧的构建产物目录，重新执行npm run build生成新的静态文件，推送到GitHub Pages对应分支后，清理浏览器缓存再访问即可正常加载，不需要手动点击“Inicio”导航。

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