React应用部署到GitHub Pages后无法加载且图片不显示，求解决方案

问题背景 #

本地用npm start运行完全正常的React应用，部署到GitHub Pages后出现两个问题：应用无法正常加载，图片也无法显示。

已尝试的排查步骤：

• 在package.json中配置"homepage": "https://lwilliams002.github.io/Stockboard/"
• 修改组件内图片导入为import userImage from 'assets/user.jpg'并在JSX中使用
• 将图片迁移至public文件夹，调整JSX引用代码
• 合并根目录与src目录下的两个package.json文件，保留根目录版本并删除src下的文件
• 更新package.json的脚本配置：

  "scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject",
    "predeploy": "npm run build",
    "deploy": "gh-pages -d build"
  }
  

• 修正createRoot的导入路径，从react-dom/client导入而非react-dom

额外可行的解决/排查步骤 #

1. 确认GitHub Pages部署源 #

进入仓库的Settings → Pages页面，检查部署源是否选择了gh-pages分支。若之前选择的是其他分支（如main），切换为gh-pages后点击保存，等待重新部署。

2. 验证build产物的资源路径 #

本地执行npm run build后，打开build/index.html，查看JS、CSS、图片等资源的引用路径是否包含仓库名称前缀。如果是无前缀的绝对路径，检查package.json中的homepage配置是否存在拼写错误（比如大小写、多余/缺失斜杠）。

3. 规范public文件夹图片的引用方式 #

若图片存放在public文件夹，JSX中必须使用%PUBLIC_URL%占位符或结合环境变量的绝对路径，示例：

// 正确写法
<img src={`${process.env.PUBLIC_URL}/user.jpg`} alt="用户头像" />
// 或使用占位符
<img src="%PUBLIC_URL%/user.jpg" alt="用户头像" />

避免使用相对路径（如./user.jpg），否则部署后会因根路径变化导致资源找不到。

4. 检查gh-pages分支的完整性 #

打开仓库的gh-pages分支，确认build文件夹的所有文件都已正确推送，无遗漏或损坏。若内容不全，重新执行npm run deploy，观察终端输出是否有报错（如权限不足、网络中断）。

5. 强制清除浏览器缓存 #

部署后浏览器可能缓存旧资源，按Ctrl+Shift+R（Windows/Linux）或Cmd+Shift+R（Mac）强制刷新页面，或使用隐私窗口访问验证。

6. 适配React Router路由（若使用） #

如果应用使用了React Router，必须替换BrowserRouter为HashRouter——因为GitHub Pages不支持单页应用的路由重写规则，示例：

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

function App() {
  return (
    <Router>
      <Routes>
        {/* 路由配置 */}
      </Routes>
    </Router>
  );
}

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