React项目本地运行正常，build后部署无内容显示求助

常见问题及修复步骤 #

1. 配置正确的homepage字段 #

打开项目根目录的package.json，添加或修改homepage字段，格式适配你的仓库：

"homepage": "https://TianMeds.github.io/official-portfolio"

如果是用户主页类型的仓库（如username.github.io），则设置为"homepage": "."。

2. 调整路由配置（若使用React Router） #

GitHub Pages的静态服务器不支持BrowserRouter的前端路由解析，会导致组件无法加载或路由异常，可通过两种方式修复：

• 替换为HashRouter：

import { HashRouter as Router, Routes, Route } from 'react-router-dom';

function App() {
  return (
    <Router>
      {/* 你的路由内容 */}
    </Router>
  );
}

• 保留BrowserRouter并添加basename属性：

<Router basename="/official-portfolio">
  {/* 你的路由内容 */}
</Router>

3. 检查build后的资源路径 #

执行npm run build后，打开build/index.html，确认JS、CSS等资源的引用路径是相对路径（如./static/js/main.xxx.js），而非绝对路径（/static/js/...）。绝对路径会导致GitHub Pages无法正确定位资源。

4. 确认GitHub Pages部署源 #

进入GitHub仓库的Settings > Pages页面：

• 在「Source」区域选择Deploy from a branch
• 分支选择gh-pages（手动推送build产物或通过Actions自动生成的分支），文件夹选择/root
• 保存后等待部署完成，刷新页面验证效果。

5. 检查build脚本有效性 #

确认package.json中的build命令配置正确，TypeScript项目需确保编译流程正常：

"scripts": {
  "build": "react-scripts build"
}

6. 利用浏览器控制台排查错误 #

部署后按F12打开开发者工具，切换到「Console」标签，查看是否存在资源加载404、语法报错等信息，根据具体提示定位问题（比如资源路径错误、组件渲染异常等）。

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