React应用部署GitHub Pages出现404、空白页问题求助

两个配置错误直接导致了404和空白页问题：

• 部署分支配置不匹配：package.json中deploy脚本写了-b master参数，会把构建产物推送到master分支，和你后续设置的GitHub Pages部署源gh-pages分支完全不对应，部署分支拿不到正确的index.html文件就会返回404错误。
• 路由模式不兼容：你在devDependencies中安装了react-router-dom@6.3.0，如果项目使用BrowserRouter（history模式路由），GitHub Pages作为静态文件服务不支持这种路由的路径重写规则，加载时会找不到对应静态资源，触发页面空白。
• 额外风险：执行带-b master参数的部署命令时，gh-pages工具会直接覆盖目标分支的所有内容，如果你没有提前备份，master分支的原有源码会被构建产物替换，存在源码丢失风险。

1. 修正部署脚本
   打开项目根目录的package.json，修改scripts字段下的deploy命令，删除错误的分支指定参数，让工具默认将构建产物推送到专用的gh-pages部署分支：

"scripts": {
  "predeploy": "npm run build",
  "deploy": "gh-pages -d build",
  "start": "react-scripts start",
  "build": "react-scripts build",
  "test": "react-scripts test",
  "eject": "react-scripts eject"
}

2. 调整路由模式适配静态服务
   找到项目的路由入口文件（通常是src/index.js），将原来使用的BrowserRouter替换为HashRouter。Hash模式路由会在路径前增加#标识，所有路径跳转都不会触发静态服务器的文件查找，完全适配GitHub Pages的服务规则：

// 原引入代码：import { BrowserRouter } from 'react-router-dom';
import { HashRouter } from 'react-router-dom';
import App from './App';

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(
  <HashRouter>
    <App />
  </HashRouter>
);

3. 清理缓存重新部署

• 先删除本地项目下的build目录和node_modules/.cache目录，清除旧构建缓存避免异常。
• 如果之前执行错误部署命令覆盖了master分支，先通过git reflog找到源码最新的提交记录，执行git reset --hard <对应提交hash>回滚master分支，再执行git push -f origin master同步远程仓库的master分支，找回源码。
• 重新执行部署命令：npm run deploy，等待命令执行完成后，确认远程仓库已经自动生成gh-pages分支，且分支内存在构建后的index.html文件。

4. 校验Pages配置
   打开GitHub仓库的Settings -> Pages页面，确认Source选项选择gh-pages分支的/ (root)目录，保存配置后等待1-3分钟，等GitHub的部署缓存生效后再访问配置的homepage地址即可正常访问。

注意：GitHub Pages每次部署后都有1-5分钟的全球节点缓存同步时间，刚部署完立刻刷新大概率会拿到旧的错误页面，等待几分钟再访问即可。

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