React项目部署GitHub Pages后默认首页Hero组件不显示问题

问题场景 #

本地开发环境下，path="/"路由可正常渲染Nav、Hero、Footer组件，但部署到GitHub Pages后，访问站点仅显示导航栏和页脚，Hero组件无法加载。

现有代码 #

App.jsx #

import React from 'react'
import Nav from './components/Nav'
import Footer from './components/Footer'
import Hero from './pages/Hero'
import Aboutme from './pages/Aboutme'
import Project from './pages/Project'
import Service from './pages/Service'
import Contact from './pages/Contact'
import './App.sass'
import './style/Responsive.sass'
import {BrowserRouter as Router , Routes, Route}from 'react-router-dom'
const App = () => {
  return (
    <Router>
      <Nav></Nav>
      <Routes>
        <Route path='/' element={ <Hero></Hero> }></Route>
        <Route path='/aboutme' element={<Aboutme></Aboutme>}></Route>
        <Route path='/project' element={<Project />}></Route>
        <Route path='/service' element={<Service />}></Route>
        <Route path='/contact' element={<Contact />}></Route>
      </Routes>
      <Footer></Footer>
    </Router>
  )
}

export default App

package.json #

{
  "homepage": "https://Ashimgautam356.github.io/ReactPortfolio",
  "name": "portfolio",
  "version": "0.1.0",
  "private": true,
  "dependencies": {
    "@testing-library/jest-dom": "^5.16.5",
    "@testing-library/react": "^13.4.0",
    "@testing-library/user-event": "^13.5.0",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "react-icons": "^4.7.1",
    "react-router-dom": "^6.6.1",
    "react-scripts": "5.0.1",
    "sass": "^1.57.1",
    "web-vitals": "^2.1.4"
  },
  "scripts": {
    "start": "react-scripts start",
    "predeploy": "npm run build",
    "deploy": "gh-pages -d build",
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject"
  },
  "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": "^4.0.0"
  }
}

解决方案 #

问题根源是React Router的路由模式未适配GitHub Pages的子路径部署，你的项目部署在/ReactPortfolio子路径下，默认的BrowserRouter没有匹配这个路径前缀，导致路由匹配失败，Hero组件无法渲染。以下两种方式可修复：

方式一：为BrowserRouter添加basename属性 #

修改App.jsx中的Router组件，指定basename为仓库名称（即homepage中的子路径部分）：

// 导入部分保持不变
const App = () => {
  return (
    <Router basename="/ReactPortfolio"> {/* 添加basename属性 */}
      <Nav></Nav>
      <Routes>
        <Route path='/' element={ <Hero></Hero> }></Route>
        <Route path='/aboutme' element={<Aboutme></Aboutme>}></Route>
        <Route path='/project' element={<Project />}></Route>
        <Route path='/service' element={<Service />}></Route>
        <Route path='/contact' element={<Contact />}></Route>
      </Routes>
      <Footer></Footer>
    </Router>
  )
}

方式二：替换为HashRouter #

HashRouter通过URL哈希（#）处理路由，无需服务器额外配置，更适配静态站点部署。修改App.jsx的导入和Router组件：

// 替换导入的Router类型
import {HashRouter as Router , Routes, Route}from 'react-router-dom'

const App = () => {
  return (
    <Router>
      <Nav></Nav>
      <Routes>
        <Route path='/' element={ <Hero></Hero> }></Route>
        <Route path='/aboutme' element={<Aboutme></Aboutme>}></Route>
        <Route path='/project' element={<Project />}></Route>
        <Route path='/service' element={<Service />}></Route>
        <Route path='/contact' element={<Contact />}></Route>
      </Routes>
      <Footer></Footer>
    </Router>
  )
}

验证修复 #

修改完成后，重新执行部署命令：

npm run deploy

部署完成后访问GitHub Pages站点，即可正常加载所有组件。

内容的提问来源于stack exchange，提问作者ASHIM GAUTAM