将React应用部署到GitHub Pages时跳转至README文件的问题求助

核心问题定位 #

你遇到的情况本质是GitHub Pages没有读取到gh-pages分支里的React构建文件，反而 fallback 显示了仓库的README。下面逐个拆解可能的原因和对应的排查逻辑：

1. 先确认gh-pages分支的实际内容 #

这是最关键的一步：

• 打开你的GitHub仓库，切换到gh-pages分支，查看根目录下的文件。正常应该有index.html、static文件夹这些build生成的内容，而不是主分支的README.md。
• 如果gh-pages分支里全是主分支的内容，说明npm run deploy没有正确把build文件推送到该分支。

为什么会出现这种情况？ #

• 本地build目录为空：先手动执行npm run build，检查本地项目根目录下的build文件夹是否生成了完整的文件。如果build失败（比如终端报错依赖缺失、语法错误），那deploy自然没有内容可推。
• gh-pages包执行出错：重新运行npm run deploy，仔细看终端输出，有没有权限报错（比如SSH密钥验证失败）、路径错误（比如找不到build目录）。

2. .gitignore的修改其实没必要 #

gh-pages包推送build内容的逻辑是：直接读取本地build目录的文件，单独构建一个临时git仓库推送到gh-pages分支，完全不受主分支.gitignore的影响。你修改.gitignore的操作对deploy流程没有帮助，反而可能混淆分支状态。

3. 检查package.json的配置细节 #

• homepage字段：必须严格匹配https://<username>.github.io/<repo-name>，注意用户名和仓库名要和GitHub上的完全一致（GitHub用户名不区分大小写，但建议用注册时的拼写；仓库名必须完全一致）。如果这个字段写错，可能导致React路由或资源加载失败，但不会直接显示README，不过还是要确认。
• deploy脚本："deploy": "gh-pages -d build"是正确的，-b gh-pages是指定分支的参数，默认就是gh-pages，所以加不加都可以。但要确保执行脚本时，你在有完整源代码的分支（比如main/master），因为predeploy会先执行build。

4. GitHub Pages的部署设置错误 #

进入仓库的Settings -> Pages，确认：

• Source选择的是gh-pages分支
• 下方的目录选择的是/root（根目录），而不是/docs或其他目录。如果选了/docs，GitHub会去gh-pages分支的docs目录找文件，而你的build内容在根目录，自然找不到，就会 fallback 显示README。

5. 部署延迟或浏览器缓存 #

GitHub Pages第一次部署或更新后，可能有5-10分钟的延迟。如果确认gh-pages分支内容正确、设置也没问题，等一会儿再刷新页面，或者用无痕模式打开（避免浏览器缓存旧内容）。

快速排查步骤总结 #

• 本地执行npm run build，确认build目录有正确的文件。
• 检查GitHub上gh-pages分支的文件列表，确认有build生成的内容。
• 检查仓库Settings -> Pages的Source配置，确保是gh-pages分支的根目录。
• 清除缓存或用无痕窗口访问，等待部署生效。

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