ReactJS应用部署到GitHub Pages后显示空白页问题求助

DevOps 小满

2026-10-9

React 部署 GitHub Pages 空白页排查方案

修正配置语法错误：你提供的 package.json 配置片段存在JSON语法问题，homepage 项后多余逗号、scripts 字段前多了无效的闭合大括号，会导致配置完全不生效，请先修正为合法格式：
```
{
  "homepage": "https://DroidBarber.github.io/dolla/",
  "scripts": {
    "predeploy": "npm run build",
    "deploy": "gh-pages -d build"
  }
}
```
路由模式调整：如果你项目使用了 react-router 的 BrowserRouter 模式，GitHub Pages 作为静态文件服务不支持 history 路由，会导致资源路径匹配失败出现空白，请替换为 HashRouter 模式后重新打包部署。
验证打包产物有效性：本地执行 npm run build 完成打包后，运行 npx serve -s build 启动本地静态服务访问打包产物，如果本地访问也空白，说明是打包环节的问题，和部署流程无关，优先排查项目代码依赖、语法错误等问题。
检查资源路径配置：打开你仓库 gh-pages 分支的 index.html 文件，查看其中引入的 JS、CSS 资源路径是否带有 /dolla/ 前缀（例如路径应为 /dolla/static/js/main.xxx.js）。如果路径没有对应前缀，说明 homepage 配置未生效。
如果你是用 Vite 搭建的 React 项目，除了配置 homepage 外，还需要在 vite.config.js 中添加 base: '/dolla/' 配置项。
缓存排查：部署完成后等待 1-3 分钟让 GitHub Pages 生效，使用浏览器隐身窗口访问页面，排除本地缓存导致的空白问题。