React项目构建部署成功却显示空白页，报404资源加载失败

• 检查package.json的homepage字段，必须设置为你的GitHub Pages站点地址：

  "homepage": "https://joonhyoo.github.io/test-site/"
  

  无此字段则直接添加到文件根节点，这是webpack正确生成静态资源路径的核心配置。

• 确保部署依赖与脚本配置正确：

  1. 安装gh-pages依赖：

     npm install gh-pages --save-dev
     

  2. 在package.json的scripts中添加部署相关命令：

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

  完成后重新执行npm run deploy触发构建与部署。

• 处理React Router路由问题：
  GitHub Pages不支持单页应用的BrowserRouter路由（刷新会触发404），需替换为HashRouter：

  // 替换前
  import { BrowserRouter } from 'react-router-dom';
  // 替换后
  import { HashRouter } from 'react-router-dom';
  
  ReactDOM.render(
    <HashRouter>
      <App />
    </HashRouter>,
    document.getElementById('root')
  );
  

• 确认GitHub Pages部署设置：
  进入仓库的Settings → Pages页面，检查部署分支是否为gh-pages，文件夹是否选择/root，保存设置后等待部署完成。

• 验证本地构建资源路径：
  本地执行npm run build后，打开build/index.html，查看静态资源（JS/CSS/图片）的引用路径是否包含仓库名（如/test-site/static/js/main.xxx.js），路径错误则说明homepage配置有误。

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