React项目本地运行正常，部署至gh-pages后显示空白求助

问题背景 #

开发React项目时，原本遇到gh-pages默认打开Notebook组件而非Login组件的问题。将与GitHub仓库同名的Notebook组件重命名为Note后，本地运行正常，但gh-pages部署后显示空白页面。尝试过修改package.json的方案，未解决问题。

排查与解决步骤 #

1. 适配GitHub Pages子路径的路由配置 #

gh-pages部署在/notebook/子路径下，需给BrowserRouter添加basename属性：

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

ReactDOM.render(
  <BrowserRouter basename="/notebook/">
    <App />
  </BrowserRouter>,
  document.getElementById('root')
);

同时确保Login组件为默认路由或设置重定向：

<Routes>
  <Route path="/" element={<Navigate to="/login" replace />} />
  <Route path="/login" element={<Login />} />
  <Route path="/note" element={<Note />} />
</Routes>

2. 排查组件重命名后的引用遗漏 #

全局搜索项目中所有Notebook的引用，确保全部替换为Note，包括导入语句、路由配置、Redux逻辑等。本地运行正常可能依赖缓存，但生产构建会暴露未修复的引用错误。执行npm run build后，检查build文件夹是否正常生成，有无构建报错。

3. 清理gh-pages缓存 #

删除本地gh-pages分支后重新部署：

git branch -D gh-pages
npm run deploy

也可在GitHub仓库的「Settings -> Pages」中，暂时切换源到其他分支再切回gh-pages，触发重新构建。

4. 升级react-scripts版本 #

当前使用的react-scripts@2.1.8版本较旧，可能存在兼容性问题，建议升级到稳定版本：

npm install react-scripts@5.0.1 --save

升级后重新执行npm run build和npm run deploy。

5. 查看生产环境控制台报错 #

部署后打开浏览器开发者工具（F12），切换到Console标签，查看是否有JS报错（如组件未找到、资源加载失败等），根据报错信息精准定位问题。

项目package.json配置 #

{
  "name": "notebook",
  "version": "0.1.0",
  "private": true,
  "homepage" : "https://thewizard91.github.io/notebook/",
  "dependencies": {
    "@googlemaps/react-wrapper": "^1.1.18",
    "@reduxjs/toolkit": "^1.7.1",
    "@testing-library/jest-dom": "^5.16.1",
    "@testing-library/react": "^12.1.2",
    "@testing-library/user-event": "^13.5.0",
    "babel-preset-react": "^6.24.1",
    "bootstrap": "^5.2.1",
    "firebase": "^9.9.4",
    "gulp": "^3.9.1",
    "react": "^17.0.2",
    "react-bootstrap": "^2.5.0",
    "react-dom": "^17.0.2",
    "react-redux": "^7.2.6",
    "react-router-dom": "^6.2.1",
    "react-scripts": "^2.1.8",
    "redux": "^4.1.2",
    "redux-thunk": "^2.4.1",
    "semantic-ui-css": "^2.4.1",
    "semantic-ui-react": "^2.0.4",
    "serve": "^14.2.0",
    "styled-components": "^5.3.3",
    "web-vitals": "^2.1.2"
  },
  "scripts": {
    "predeploy": "npm run build",
    "deploy": "gh-pages -d build -b gh-pages",
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject",
    "heroku-postbuild": "npm run build"
  },
  "heroku-run-build-script": true,
  "eslintConfig": {
    "extends": [
      "react-app",
      "react-app/jest"
    ]
  },
  "browserslist": {
    "production": [
      ">0.2%",
      "not dead",
      "not op_mini all"
    ],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  },
  "devDependencies": {
    "gh-pages": "^3.2.3"
  },
  "engines": {
    "node": "16.18.1",
    "npm": "8.19.2"
  }
}

内容的提问来源于stack exchange，提问作者Emmanuel Kofy Agyapong