React项目部署gh-pages后页面空白，本地运行正常求助

核心排查与修复步骤 #

1. 补全/修正package.json的homepage配置 #

gh-pages部署依赖正确的homepage字段，必须匹配你的GitHub Pages访问路径：

• 若为用户主页仓库（仓库名是<你的用户名>.github.io），设为"homepage": "https://<用户名>.github.io/"
• 若为普通项目仓库，设为"homepage": "https://<用户名>.github.io/<仓库名>/"
• 也可使用相对路径"homepage": "./"适配所有场景

示例配置片段：

{
  "homepage": "https://yourname.github.io/portfolio/",
  "scripts": {
    "predeploy": "npm run build",
    "deploy": "gh-pages -d build"
  }
}

配置完成后重新执行npm run deploy。

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

GitHub Pages不支持前端路由的直接访问与刷新，必须将BrowserRouter替换为HashRouter：

// index.js中修改路由导入与使用
import { HashRouter as Router } from 'react-router-dom';

ReactDOM.createRoot(document.getElementById('root')).render(
  <Router>
    <App />
  </Router>
);

3. 检查build产物的资源路径 #

执行npm run build后，打开build/index.html，确认所有js、css资源路径为相对路径（如./static/js/main.xxx.js）。如果是绝对路径（/static/js/...），说明homepage配置错误，修正后重新build部署。

4. 验证部署分支与内容 #

登录GitHub仓库，切换到gh-pages分支，确认该分支下的文件是build文件夹的完整内容，没有遗漏或上传错误。

5. 强制刷新浏览器缓存 #

按Ctrl+Shift+R强制刷新页面，或使用无痕模式访问，排除旧缓存导致的空白问题。

针对你的代码文件的额外检查点 #

• index.html：确保<div id="root"></div>存在且未被修改，无额外阻塞渲染的代码
• App.js：确认组件正确导出（export default App;），build过程无报错（查看终端输出日志）
• index.js：确认React挂载逻辑正确，React 18需使用createRoot，避免旧版render写法的隐性问题

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