GitHub Pages部署React应用显示空白页问题咨询

本地运行正常、部署后空白，核心问题基本集中在子路径适配和路由配置上，按以下步骤逐一排查修复：

• 配置React Router的basename参数
  你的项目部署在https://ThreadSurfer.github.io/MyPortfolio子路径下，使用了react-router-dom v6做路由，必须给根路由组件添加basename属性，否则路由无法匹配到对应路径，直接渲染空白。
  找到项目中引入BrowserRouter的入口文件（通常是src/index.js或src/App.js），将原有的路由标签修改为：

  <BrowserRouter basename="/MyPortfolio">
    {/* 你的原有路由配置 */}
  </BrowserRouter>
  

  注意basename的值必须和package.json中homepage字段的路径后缀完全一致，和GitHub仓库名的大小写也要完全匹配。

• 补充单页应用路由重定向配置
  GitHub Pages默认不支持前端路由，直接访问子路径、刷新页面会返回404，需要做重定向适配：

  1. 在项目public目录下新建404.html文件，内容和public/index.html的内容完全一致
  2. 在public/404.html的head标签最顶部添加以下代码：

  <script>
    sessionStorage.redirect = location.href;
  </script>
  <meta http-equiv="refresh" content="0;URL='/MyPortfolio'">
  

  3. 在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. 删掉本地旧的build文件夹
  2. （可选）清理package.json冗余依赖：你在dependencies和devDependencies中重复声明了gh-pages包，可以删掉dependencies中的gh-pages条目，不影响功能
  3. 重新执行npm run deploy命令触发部署
  4. 等GitHub仓库Pages页面显示部署成功（绿色对勾标识）后，清空浏览器缓存再访问页面

• 报错排查
  如果改完还是空白，打开浏览器开发者工具的Console面板看报错：

  • 如果报js/css静态资源404：检查package.json中homepage字段的拼写，确认仓库名大小写、用户名拼写完全和GitHub实际地址一致
  • 如果报权限相关错误：确认仓库Settings-Pages页面的部署源选择正确，使用gh-pages部署时要选gh-pages分支的根目录作为源，不要选其他分支或子文件夹

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