React应用部署GitHub Pages后初始白屏问题求助

可能原因及解决步骤 #

1. 检查package.json的homepage配置 #

确保homepage字段正确匹配GitHub Pages的子路径：

"homepage": "https://brandonawilliams1.github.io/brandon-profile/"

或者使用相对路径适配子目录部署场景：

"homepage": "./"

修改后重新执行npm run build，再重新部署到GitHub Pages。

2. 修正React Router的basename配置 #

如果使用BrowserRouter，必须添加basename属性对应仓库子目录，否则首次加载时路由匹配会异常：

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

function App() {
  return (
    <BrowserRouter basename="/brandon-profile">
      {/* 你的路由组件内容 */}
    </BrowserRouter>
  );
}

3. 验证资源引用路径 #

• 打开本地构建生成的build/index.html，检查CSS、JS等资源的引用路径：若路径以/开头（如/static/css/main.xxx.css），在子目录部署下会无法找到资源，homepage配置会自动修正为正确的子目录路径
• 若手动在public/index.html中引入CSS，需使用%PUBLIC_URL%前缀保证路径正确：

<link rel="stylesheet" href="%PUBLIC_URL%/your-style-file.css">

4. 通过浏览器控制台定位具体错误 #

打开部署页面的浏览器开发者工具（F12）：

• 切换到Network标签，查看CSS文件的请求状态，若显示404则说明路径错误
• 查看Console标签的报错信息，直接定位资源加载或路由匹配的具体问题

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