为何我的github.io主页（react-gh-pages部署）显示404错误？

• 检查仓库核心配置
  确认ryan-howard-hc.github.io仓库的Settings → Pages中，Source选择的是gh-pages分支且根目录为/root，个人主页仓库必须指定根目录，这是和子项目部署的核心区别之一。

• 核对package.json关键字段

  • 确保homepage设置为"https://ryan-howard-hc.github.io/"（末尾需带斜杠，子项目是"/ReactMenu"，主页要直接指向域名根路径）
  • 检查scripts里的deploy命令为"deploy": "gh-pages -d build"，不要添加额外路径参数，保证build产物直接推送到gh-pages分支根目录。

• 修复React路由兼容问题
  若项目使用了react-router，个人主页必须改用HashRouter替代BrowserRouter——GitHub Pages不支持SPA的history模式，根路径下刷新会触发404。示例代码替换：

  import { HashRouter as Router, Route, Routes } from 'react-router-dom';
  

• 重新部署并清理缓存

  • 删除本地build文件夹和node_modules/.cache目录，执行命令重新构建部署：

    npm run build
    npm run deploy
    

  • 部署完成后等待5-10分钟（GitHub Pages存在延迟），再强制刷新浏览器（Ctrl+F5）清除缓存。

• 验证gh-pages分支内容
  进入仓库的gh-pages分支，确认存在完整的build产物（index.html、static文件夹等），若内容缺失，检查部署过程中的终端报错信息排查问题。

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