在GitHub Pages部署单页React应用出现空白页求助

常见成因 #

• 静态资源/路由基础路径不匹配：GitHub Pages部署的项目运行在子路径（/my-chat-app/）下，但React默认以根路径（/）加载资源、解析路由，导致资源找不到或路由解析失败，页面空白。
• 路由模式不兼容：使用BrowserRouter时，GitHub Pages的静态服务器不支持前端路由的刷新/直接访问，初始加载可能因路由解析异常导致空白。
• 部署脚本或分支配置错误：未正确配置构建产物的推送路径，或者GitHub Pages未指定正确的部署分支/目录。

修复步骤 #

1. 配置项目基础路径 #

在项目根目录的package.json中添加homepage字段，指定项目的部署子路径：

"homepage": "/my-chat-app/"

添加后，React构建时会自动为所有静态资源路径加上/my-chat-app/前缀，避免资源加载404。

2. 调整路由配置 #

如果使用React Router：

• 若用BrowserRouter，必须设置basename属性匹配子路径：

import { BrowserRouter } from 'react-router-dom';

ReactDOM.render(
  <BrowserRouter basename="/my-chat-app">
    {/* 你的路由组件内容 */}
  </BrowserRouter>,
  document.getElementById('root')
);

• 想更省心的话，直接改用HashRouter——它基于URL哈希值处理路由，不受服务器配置限制，完全适配GitHub Pages环境：

import { HashRouter } from 'react-router-dom';

ReactDOM.render(
  <HashRouter>
    {/* 你的路由组件内容 */}
  </HashRouter>,
  document.getElementById('root')
);

3. 配置并执行部署脚本 #

1. 安装gh-pages部署工具：

npm install gh-pages --save-dev

2. 在package.json的scripts中添加部署命令：

"scripts": {
  // 保留原有脚本...
  "predeploy": "npm run build",
  "deploy": "gh-pages -d build"
}

3. 执行部署命令：

npm run deploy

该命令会自动构建项目，并把build目录的产物推送到仓库的gh-pages分支。

4. 确认GitHub Pages设置 #

登录GitHub仓库，进入「Settings」→「Pages」：

• 确认「Source」选择的是gh-pages分支，目录为/root；
• 等待1-5分钟部署完成后，再刷新访问页面。

5. 排查控制台错误 #

如果还是空白，打开浏览器开发者工具（F12）的「Console」标签：

• 若有资源加载404，检查homepage字段是否配置正确；
• 若有路由相关报错，检查basename设置或路由模式是否适配。

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