React项目本地可运行但GitHub Pages部署后无法启动求助

我用React JS构建的movie-app项目在本地localhost环境下能正常运行，但部署到GitHub Pages后，尽管代码已成功推送至仓库，应用却无法正常运行。部署后的项目地址为xcage88.github.io/movie-app。

项目配置文件（package.json） #

{
  "name": "movie-app",
  "version": "0.1.0",
  "homepage": "http://xcage88.github.io/movie-app",
  "private": true,
  "dependencies": {
    "@fortawesome/fontawesome-svg-core": "^6.2.1",
    "@fortawesome/free-solid-svg-icons": "^6.2.1",
    "@fortawesome/react-fontawesome": "^0.2.0",
    "@testing-library/jest-dom": "^5.16.5",
    "@testing-library/react": "^13.4.0",
    "@testing-library/user-event": "^13.5.0",
    "bootstrap": "^5.2.3",
    "gh-pages": "^5.0.0",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "react-scripts": "5.0.1",
    "web-vitals": "^2.1.4"
  },
  "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"
  },
  "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": {
    "react-router-dom": "^6.8.0"
  }
}

核心代码 #

App.js #

import { Route, Routes } from 'react-router-dom';
import SignUp from './component/SignUp';
import ForgotForm from './component/ForgotForm';
import LoginForm from './component/LoginForm';
import MainPage from './component/MainPage';

function App() {
  return (
    <div>
      <div>
        <Routes>
          <Route path='/' exact element={<LoginForm/>}/>
          <Route path='/forgot' element={<ForgotForm/>}/>
          <Route path='/sign-up' element={<SignUp/>}/>
          <Route path='/main/*' element={<MainPage/>}/>
        </Routes>
      </div>
    </div>
  );
}

export default App;

index.js #

import React from 'react';
import ReactDOM from 'react-dom/client';
import './style/style.css'
import 'bootstrap/dist/css/bootstrap.css'
import 'bootstrap/dist/js/bootstrap.bundle'
import reportWebVitals from './reportWebVitals';
import {BrowserRouter} from 'react-router-dom'

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(
  <React.StrictMode>
    <BrowserRouter>
      <App />
    </BrowserRouter>
  </React.StrictMode>
);

效果对比 #

• 本地运行：正常显示登录界面，路由跳转功能正常
• GitHub Pages部署后：页面无法正常加载组件，显示异常

解决方案 #

1. 配置React Router的基础路径 #

GitHub Pages部署的项目位于子路径/movie-app下，React Router默认使用根路径，导致路由无法匹配。修改index.js中的BrowserRouter，添加basename属性：

<BrowserRouter basename="/movie-app">
  <App />
</BrowserRouter>

2. 检查静态资源引用 #

确保项目中所有静态资源（图片、字体等）的引用使用相对路径，或通过process.env.PUBLIC_URL拼接路径，例如：

<img src={`${process.env.PUBLIC_URL}/images/logo.png`} alt="Logo" />

3. 重新部署 #

修改完成后，执行以下命令重新部署到GitHub Pages：

npm run deploy

内容的提问来源于stack exchange，提问作者Hovi Sohibul Wafa