React项目部署GitHub Pages显示空白屏问题排查

核心问题定位 #

空白页问题基本由以下两个原因导致：

• 路由配置缺少子路径前缀：项目使用react-router-dom v6做路由管理时，如果用的是BrowserRouter模式，部署在/ECommerceSite这种项目子路径下，必须显式配置basename参数，否则路由初始化时匹配不到对应路径，直接返回空内容。
• 路径大小写不统一：package.json中配置的homepage字段用户名为大写开头Bcruise，实际访问的站点域名为小写开头bcruise，部分浏览器静态资源解析时会因为路径大小写不匹配报404，导致脚本无法加载。

修复操作步骤 #

• 修正路由配置
  找到项目路由挂载的入口文件（通常是src/index.js或src/App.js），给BrowserRouter组件添加basename属性，值和你的项目子路径完全一致：

// 原错误写法
<BrowserRouter>
  <App />
</BrowserRouter>

// 修改后
<BrowserRouter basename="/ECommerceSite">
  <App />
</BrowserRouter>

如果不想额外配置basename，可以直接把BrowserRouter替换成HashRouter，Hash模式路由不会受部署子路径影响，不需要额外参数，适配GitHub Pages更简单：

// 引入时直接替换
import { HashRouter as Router } from 'react-router-dom';

// 挂载使用
<Router>
  <App />
</Router>

• 修正package.json配置
  把homepage字段改成和实际访问地址完全一致的格式，统一用户名大小写：

"homepage": "https://bcruise.github.io/ECommerceSite"

• 清理缓存重新部署
  在项目根目录执行以下命令，清除旧构建产物后重新发布：

# 删除旧构建文件和构建缓存
rm -rf build node_modules/.cache
# 重新执行部署命令，会自动触发build再推送到gh-pages分支
npm run deploy

兜底排查清单 #

如果以上操作完成后还是空白，按顺序检查：

• 打开浏览器开发者工具的Console面板，看是否有JS报错、静态资源404报错，如果是js/css文件404，检查构建后生成的build/index.html里的资源引用路径是否以/ECommerceSite/开头，没有的话说明homepage配置未生效，重新执行build即可。
• 进入GitHub仓库的Settings-Pages配置页，确认部署源选择的是gh-pages分支的根目录，不要选错分支或目录。
• 检查代码中所有静态资源引用，不要直接写/xxx.png这种根路径格式，统一用相对路径或者%PUBLIC_URL%/xxx.png的格式引用public目录下的资源，避免子路径下资源加载失败。

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