React项目部署至GitHub Pages后页面空白、静态资源404如何解决？

问题根因 #

你遇到的404、空白页问题核心是GitHub Pages站点部署在/monsters/子路径下，但React项目默认配置的资源请求路径是站点根路径，导致js、css等静态资源请求地址错误，无法加载。

具体修复步骤 #

• 第一步：配置项目路径前缀
  打开项目根目录的package.json文件，在顶层添加homepage字段：

"homepage": "https://ksxv.github.io/monsters/"

如果后续需要兼容多部署环境，也可以简化为相对路径配置："homepage": "."

• 第二步：更新构建脚本（使用gh-pages工具部署时需要）
  在package.json的scripts字段中添加部署相关脚本：

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

• 第三步：重新生成构建产物并部署
  执行以下命令重新构建并推送产物到gh-pages分支：

npm run build
npm run deploy

• 第四步：验证仓库Pages配置
  进入GitHub仓库的Settings -> Pages页面，确认部署源选择的是gh-pages分支，目录为/(root)，等待2到3分钟部署生效后再访问站点即可正常加载。

适配React路由配置（可选） #

如果你的项目使用了React Router，还需要将路由的basename设置为仓库名，避免路由跳转404：

// React Router v6 配置示例
import { BrowserRouter } from 'react-router-dom'

<BrowserRouter basename="/monsters">
  {/* 原有路由配置 */}
</BrowserRouter>

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