React网站部署到GitHub Pages后出现空白页问题求助

React项目部署GitHub Pages空白问题排查方案 #

1. 修正package.json的homepage配置 #

这是最常见的报错原因，GitHub Pages属于子路径站点，必须在项目package.json中增加homepage字段声明站点路径：

{
  "homepage": "https://sarahacollins.github.io/Portfolio/"
}

注意仓库名大小写要和实际一致，漏加该字段会导致打包后的资源引用路径错误，无法加载js/css文件导致页面空白。

2. 确认部署源配置正确性 #

你当前使用gh-pages作为部署源的配置是正确的：master分支存储项目源码，根目录没有可直接运行的index.html文件，因此直接设置master为部署源会返回404。
需要检查gh-pages分支的根目录结构，确保根目录下直接存在index.html、static文件夹等打包产物，不要出现所有产物都嵌套在build文件夹内再上传的情况，否则根目录找不到入口文件会空白。

3. 路由配置适配 #

如果项目使用了react-router等路由工具：

• 优先使用HashRouter代替BrowserRouter，避免GitHub Pages不支持前端路由重定向的问题
• 如果一定要用BrowserRouter，需要给路由增加basename配置，示例如下：

// react-router v6 示例
import { BrowserRouter } from 'react-router-dom'

<BrowserRouter basename="/Portfolio">
  {/* 路由规则 */}
</BrowserRouter>

4. 标准化部署流程 #

推荐使用官方gh-pages工具自动完成打包上传，避免手动操作分支出错：

• 安装依赖：npm install gh-pages --save-dev
• 在package.json的scripts节点新增两个命令：

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

• 后续部署仅需执行npm run deploy，工具会自动将打包生成的build目录内容推送到gh-pages分支。

5. 缓存问题处理 #

配置修正完成后如果仍显示空白，可以先执行硬刷新（Windows按Ctrl+Shift+R、Mac按Cmd+Shift+R）清除本地缓存，或等待1-5分钟待GitHub Pages CDN节点更新后再访问。

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