GitHub Pages用户页显示空白：React项目部署问题求助

问题背景 #

创建极简React.js网站，部署为GitHub Pages用户页（访问地址：propertycashflowapp.github.io），本地运行npm start正常，但部署后页面空白。已尝试移动index.html到根目录、修改package.json的homepage配置、用<BrowserRouter basename={process.env.PUBLIC_URL}>包裹<App />，均未解决。

项目目录结构：

├── README.md
├── index.html (与public目录下的文件重复)
├── package-lock.json
├── package.json
├── public
│   ├── favicon.ico
│   ├── index.html
│   ├── logo192.png
│   ├── logo512.png
│   ├── manifest.json
│   └── robots.txt
└── src
    ├── App.css
    ├── App.js
    ├── App.test.js
    ├── index.css
    ├── index.js
    ├── logo.svg
    ├── reportWebVitals.js
    └── setupTests.js

排查与解决步骤 #

1. 删除根目录冗余的index.html #

根目录的index.html与public目录下的文件重复，会干扰GitHub Pages的文件加载逻辑。直接删除根目录的该文件，保留public目录下的index.html即可——create-react-app构建时会自动处理public目录下的文件并输出到build目录。

2. 修正package.json配置 #

• 设置正确的homepage：
  推荐使用相对路径配置，避免绝对路径的适配问题：

  "homepage": "."
  

  或者指定完整地址（注意末尾不要加斜杠）：

  "homepage": "https://propertycashflowapp.github.io"
  

• 添加规范的部署脚本：
  在scripts中加入以下内容，确保构建和部署流程正确：

  "scripts": {
    "predeploy": "npm run build",
    "deploy": "gh-pages -d build"
  }
  

  （如果尚未安装gh-pages，先执行npm install gh-pages --save-dev）

3. 调整路由配置（若使用React Router） #

GitHub Pages不支持单页应用的BrowserRouter路由刷新，可改用HashRouter规避这个问题：

// src/index.js
import React from 'react';
import ReactDOM from 'react-dom/client';
import { HashRouter } from 'react-router-dom';
import App from './App';

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(
  <HashRouter>
    <App />
  </HashRouter>
);

4. 手动验证构建与部署 #

• 先执行npm run build，检查build目录下的文件是否完整，打开build目录的index.html，确认js、css资源的引用路径是否正确（无404报错）。
• 若自动部署脚本无效，手动推送build目录到仓库主分支：

  git add build && git commit -m "deploy built assets"
  git subtree push --prefix build origin main
  

5. 确认GitHub Pages设置 #

进入仓库的「Settings」→「Pages」页面，确认部署来源选择的是main分支的/root目录，而非其他分支或路径。

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