React部署Github Pages显示空白页问题求助

1. 确认基础配置是否正确 #

• package.json的homepage：设为"homepage": "."（相对路径适配用户主页仓库场景），保存后重新执行构建命令npm run build。如果是子路径仓库才需要填完整地址，你的仓库是用户主页仓库（仓库名匹配域名），用相对路径更稳妥。
• BrowserRouter的basename：如果用React Router v6+，你的场景下可以直接省略basename，或者设为"/"，因为根路径就是站点地址。如果之前设了错误的子路径，会导致路由匹配失败出现空白。示例：

  <BrowserRouter>
    {/* 路由内容 */}
  </BrowserRouter>
  

2. 检查构建产物路径 #

• 打开本地build文件夹里的index.html，查看css、js文件的引入路径是否为相对路径（比如./static/js/main.xxx.js）。如果是绝对路径（/static/...），会导致Github Pages加载不到资源，用homepage: "."可以生成相对路径解决这个问题。
• 本地直接打开build/index.html，如果本地也是空白，说明构建本身有问题，不是部署的锅。此时看本地控制台报错，排查代码语法错误、依赖缺失等问题。

3. 核对Github Pages部署设置 #

• 进入仓库Settings -> Pages，确认Source选择Deploy from a branch，分支选gh-pages（如果用gh-pages工具部署），或者如果直接部署main分支的build文件夹，要确保路径设置为/build。
• 部署后等几分钟再刷新，Github Pages有时候有部署延迟，不要刚点完就急着验证。

4. 结合控制台截图排查具体错误 #

• 如果控制台报404，直接回到步骤1调整homepage和资源路径。
• 如果是React相关报错（比如组件导入错误、路由配置错误），检查App.js：
  • 确认所有组件导入路径正确，没有拼写错误。
  • React Router v6+要使用element={<Component />}的写法，不要再用旧的component属性。
  • 避免在组件顶层直接调用浏览器专属API（比如window），可以放到useEffect里执行，防止构建时出错。

5. 用gh-pages工具规范部署 #

如果没用到这个工具，建议按以下步骤操作：

• 安装依赖：npm install --save-dev gh-pages
• 在package.json的scripts里添加：

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

• 执行npm run deploy，工具会自动把build文件夹内容推到gh-pages分支，之后在Github Pages设置里选这个分支即可。

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