React应用部署GitHub Pages后仅显示背景无内容的求助

常见修复步骤 #

• 调整路由配置
  GitHub Pages不支持单页应用的浏览器路由模式，需改用哈希路由。如果使用React Router，将BrowserRouter替换为HashRouter：

  // 替换前
  import { BrowserRouter as Router } from 'react-router-dom';
  
  // 替换后
  import { HashRouter as Router } from 'react-router-dom';
  

• 配置package.json的homepage字段
  在项目根目录的package.json中添加对应仓库的访问路径，格式为https://<你的用户名>.github.io/<仓库名>/；若为用户名专属仓库（仓库名是<用户名>.github.io），直接填https://<你的用户名>.github.io/：

  {
    "homepage": "https://your-username.github.io/your-repo-name/"
  }
  

• 校验部署命令与流程
  推荐使用gh-pages包完成部署，确保流程正确：

  1. 安装依赖：npm install gh-pages --save-dev
  2. 在package.json的scripts中添加命令：

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

  3. 重新执行npm run deploy完成部署

• 修正静态资源引用路径
  避免使用绝对路径引用图片、样式等资源，改用相对路径或通过process.env.PUBLIC_URL拼接：

  // 错误示例
  <img src="/images/logo.png" />
  
  // 正确示例
  <img src={process.env.PUBLIC_URL + '/images/logo.png'} />
  

• 针对控制台错误排查
  如果控制台报资源加载404，优先检查上述路径配置；如果是语法错误，本地执行npm run build确认生产构建是否存在隐藏问题，修复后重新部署。

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