React应用部署至GitHub Pages后显示默认MD文件的问题排查

我来帮你排查下问题所在，你现在遇到的情况大概率是两个关键操作出错了——手动干预gh-pages分支的内容，以及缺少Create React App部署到GitHub Pages必需的homepage配置。咱们一步步来解决：

你操作中的核心问题 #

• 手动复制build到gh-pages分支并删除src是完全多余的：gh-pages包的作用就是自动把build目录的内容推送到gh-pages分支的根目录，你手动操作反而可能让分支里残留了仓库根目录的README.md（就是你看到的默认文档），GitHub Pages会优先显示根目录的README.md而非index.html，这就是问题根源。
• 缺少homepage字段配置：Create React App需要知道你的应用部署的URL前缀，否则生成的静态资源路径会出错，甚至可能导致页面无法正确加载。

修复步骤 #

1. 清理错误的gh-pages分支（可选但推荐） #

先把之前手动修改的gh-pages分支重置，避免残留文件干扰：

# 切换到gh-pages分支
git checkout gh-pages
# 清空分支所有内容
git rm -rf .
# 提交空分支的修改
git commit -m "Clean up gh-pages branch"
# 强制推送到远程仓库
git push origin gh-pages --force
# 切回主分支（比如main或master）
git checkout main

2. 在package.json中添加homepage字段 #

打开你的package.json，在顶部（name字段下方）添加homepage配置，格式根据仓库类型调整：

• 如果是普通项目仓库：

  "homepage": "https://<你的GitHub用户名>.github.io/<你的仓库名称>/",
  

  比如你的用户名是TTT2，仓库名是persona-frontend，则配置为：

  "homepage": "https://TTT2.github.io/persona-frontend/",
  

• 如果是GitHub用户主页仓库（仓库名必须是<你的用户名>.github.io）：

  "homepage": "https://<你的GitHub用户名>.github.io/",
  

3. 使用gh-pages自带的deploy命令部署 #

不需要再手动复制build或修改分支，直接运行：

# 确保依赖安装完整（你已安装gh-pages可跳过此步）
yarn install
# 执行部署，predeploy会自动先运行build生成最新产物
yarn deploy

这个命令会自动完成：

1. 运行yarn build生成最新的build目录
2. 将build目录的所有内容推送到gh-pages分支的根目录
3. 自动处理分支的提交与远程推送

4. 验证部署结果 #

• 打开GitHub仓库的Settings -> Pages，确认Source选择的是gh-pages分支，并且目录是/(root)（不是/docs）
• 等待2-3分钟让GitHub Pages完成部署，然后访问你的Pages URL，强制刷新页面（Ctrl+F5），应该就能看到你的React应用了。

额外注意事项 #

• 如果浏览器缓存导致页面仍显示旧内容，可以清除浏览器缓存，或者在URL后追加?v=1强制加载新资源。
• 如果你使用了react-router-dom的BrowserRouter，部署到GitHub Pages需要额外配置：
  • 要么改用HashRouter
  • 要么给BrowserRouter添加basename属性，值为你的仓库名：

    <BrowserRouter basename="/persona-frontend/">
      {/* 你的路由内容 */}
    </BrowserRouter>
    

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