React项目无法部署到GitHub Pages问题求助

• 检查GitHub仓库的Pages设置：
  进入仓库的「Settings」→「Pages」，确认源分支选择的是gh-pages，而非默认的main/master分支；目录选择「/(root)」。分支选错会导致GitHub展示默认页面而非你的项目内容。

• 确认gh-pages依赖已安装：
  很多人会遗漏安装gh-pages包，导致无法生成部署分支。执行命令：

  npm install gh-pages --save-dev
  

  安装完成后重新运行npm run deploy。

• 验证gh-pages分支的内容：
  部署完成后，去GitHub仓库的分支列表查看gh-pages分支是否存在，且分支内的文件是build目录下的产物（如index.html、static文件夹等），而非项目源码。如果分支为空或内容错误，说明部署命令执行异常。

• 核对homepage配置的准确性：
  确保package.json里的homepage路径与GitHub仓库名完全一致（区分大小写），比如仓库名为my-site，则配置必须是"https://username.github.io/my-site"，用户名和仓库名不能有误。

• 检查React路由配置（若使用路由）：
  如果项目用了React Router的BrowserRouter，需要添加basename属性，值与homepage的路径后缀一致：

  <BrowserRouter basename="/my-site">
    {/* 路由组件内容 */}
  </BrowserRouter>
  

  或者改用HashRouter，避免GitHub Pages不支持前端路由刷新的问题。

• 确认部署命令执行无异常：
  运行npm run deploy时查看终端输出，若有报错（如Git权限问题、build失败），需先解决对应问题。也可先单独运行npm run build，用本地服务器（如npx serve build）测试build产物是否正常，排除构建本身的问题。

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