部署React应用到GitHub Pages后仅显示README文件的问题

核心问题分析 #

你将GitHub Pages源设置为Master分支根目录，但gh-pages工具默认会把React构建产物推到独立的gh-pages分支，两者路径不匹配，导致GitHub Pages加载的是Master分支的README文件，而非React应用内容。

分步解决方案 #

• 修正GitHub Pages源设置

  1. 打开GitHub仓库页面，进入「Settings」→「Pages」
  2. 在「Source」区域，将分支从「Master」切换为「gh-pages」，目录保持「/root」后保存设置

• 清理部署缓存并重新部署
  若之前的部署残留引发异常，先执行命令清除本地gh-pages缓存：

  npx gh-pages clean
  

  再按流程重新部署：

  npm run deploy
  

• 添加package.json的homepage字段
  确保在package.json中补充正确的homepage配置，格式如下：

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

  该配置能保证React构建时生成正确的资源路径，避免页面加载404错误。

• 重新执行完整构建部署流程

  1. 删除本地build文件夹：rm -rf build（Windows系统使用rmdir /s build）
  2. 重新构建项目：npm run build
  3. 执行部署命令：npm run deploy

部署完成后刷新GitHub Pages链接，即可正常访问React应用。

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