React单页应用部署到GitHub Pages返回404错误如何解决？

1. 修正部署脚本配置 #

你当前package.json中的deploy脚本存在配置错误：

"deploy": "gh-pages -b main -d build"

其中-b main参数会将打包后的build目录内容推送到main分支，而非专门用于部署的gh-pages分支。同时你的项目.gitignore默认会忽略build目录，直接从main分支部署时，GitHub Pages找不到静态资源文件，所以无论你选择哪个分支作为部署源都会返回404。

• 修改deploy命令为默认配置，将打包产物推送到gh-pages分支：

"deploy": "gh-pages -d build"

2. 重新执行部署 #

运行以下命令完成重新打包部署：

• npm run deploy
  执行完成后进入仓库的Settings > Pages页面，确认部署源选择为gh-pages分支的/(root)目录，等待1-3分钟待GitHub Pages构建完成后再访问站点即可。

3. 处理客户端路由404问题 #

如果修复上述配置后首页可正常访问，但跳转其他路由后刷新页面仍报404，属于React单页应用客户端路由的共性问题，GitHub Pages作为静态文件服务无法识别前端路由规则，可通过以下方案解决：

• 在项目public目录下新建404.html文件，内容和index.html完全相同
• 也可以添加自动执行脚本，在打包后自动复制index.html为404.html，在package.json的scripts中新增：

"postbuild": "cp build/index.html build/404.html"

4. 路径大小写校验 #

GitHub Pages的文件路径是大小写敏感的，需检查所有静态资源文件名、路由路径的大小写是否和代码中引用的完全一致，避免因大小写不匹配导致资源加载失败。

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