React项目经gh-pages部署GitHub免费托管后页面不显示如何解决

不需要把所有代码都写入App.js文件，白屏问题核心是路由配置和GitHub Pages的托管路径规则不匹配，按以下步骤调整即可正常展示Home首页：

1. 配置路由基准路径 #

GitHub Pages托管的项目站点访问路径为https://<你的GitHub用户名>.github.io/<仓库名>/，不是域名根路径，当前路由配置没有设置子路径基准，会导致路径匹配失败渲染空白。
修改App.js中的Router配置，添加basename属性，属性值为你的仓库名（前面带斜杠），示例代码如下：

// 确认从react-router-dom正确导入依赖和页面组件
import { BrowserRouter as Router, Routes, Route } from 'react-router-dom';
import Home from './pages/Home';
import Main from './pages/Main';
import Me from './pages/Me';

function App() {
  return (
    <Router basename="/你的GitHub仓库名">
      <Routes>
        <Route path="/test" element={<Main/>}/>
        <Route path="/" element={<Home/>}/>
        <Route path="/me" element={<Me/>}/>
      </Routes>
    </Router>
  );
}

2. 修正package.json配置 #

打开项目根目录的package.json文件，添加homepage字段，值为你的gh-pages站点完整访问地址，格式参考：

"homepage": "https://<你的GitHub用户名>.github.io/<你的GitHub仓库名>"

该配置会让React打包时自动修正静态资源的引用路径，避免资源加载404导致的白屏。配置完成后重新执行打包、gh-pages发布流程即可正常访问Home首页。

3. 可选优化：解决子路由刷新404 #

GitHub Pages是静态托管服务，默认不会将子路径请求转发到入口index.html，后续如果访问/me、/test等子路由时出现刷新404，只需要把打包生成的index.html复制一份，重命名为404.html放到部署分支根目录即可，gh-pages触发404时会加载该文件，前端路由就能正常接管匹配。

关于代码存放的说明 #

完全不需要把所有代码都写在App.js中。App.js只是React项目的根组件入口，你可以根据业务模块把页面组件、公共逻辑、路由配置拆分到独立的js/jsx文件中，只要在使用时通过import正确引入即可，文件拆分不会影响路由功能和站点部署。

排查小技巧：如果调整配置后仍然白屏，直接打开浏览器开发者工具的Console面板和Network面板，优先检查是否有组件导入报错、静态资源加载404的问题，针对性修复即可。

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