React多页应用部署至GitHub Pages后显示空白页求助

第一步：设置package.json的homepage字段 #

根据你的部署类型，在package.json中添加或修改homepage：

• 若为GitHub Pages用户/组织站点（如https://<username>.github.io/）：

  "homepage": "https://<username>.github.io/"
  

• 若为GitHub Pages项目站点（如https://<username>.github.io/<repo-name>/）：

  "homepage": "https://<username>.github.io/<repo-name>/"
  

• 多环境兼容可尝试相对路径：

  "homepage": "."
  

第二步：配置Router的basename属性 #

无论使用BrowserRouter还是HashRouter，都需匹配部署路径设置basename：

• BrowserRouter示例：

  import { BrowserRouter } from 'react-router-dom';
  
  ReactDOM.render(
    <BrowserRouter basename="/<repo-name>">
      <App />
    </BrowserRouter>,
    document.getElementById('root')
  );
  

• HashRouter示例（项目站点同样需设置）：

  import { HashRouter } from 'react-router-dom';
  
  ReactDOM.render(
    <HashRouter basename="/<repo-name>">
      <App />
    </HashRouter>,
    document.getElementById('root')
  );
  

  注：用户/组织站点可将basename设为"/"或省略。

第三步：检查路由链接与组件渲染 #

• 页面跳转必须使用react-router-dom的<Link>组件，禁止用原生<a>标签：

  // 正确写法
  <Link to="/about">About</Link>
  // 错误写法
  <a href="/about">About</a>
  

• 验证App.js的路由配置，确保path和element匹配无拼写错误：

  import { Routes, Route } from 'react-router-dom';
  import Home from './Home';
  import About from './About';
  
  function App() {
    return (
      <div className="App">
        <Navbar />
        <Routes>
          <Route path="/" element={<Home />} />
          <Route path="/about" element={<About />} />
        </Routes>
      </div>
    );
  }
  

第四步：确认构建与部署流程 #

• GitHub Pages：确保部署build文件夹内容。若用gh-pages包，检查脚本配置：

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

  执行npm run deploy后，确认仓库gh-pages分支包含完整build文件。
• Netlify：在站点设置中确认构建命令为npm run build，发布目录为build，无路径配置错误。

第五步：排查浏览器控制台错误 #

打开开发者工具（F12），查看Console和Network标签：

• 若有404错误，检查JS/CSS等资源加载路径是否匹配homepage设置。
• 若有语法错误，排查组件导入、路由路径等拼写或语法问题。

额外提示 #

使用BrowserRouter部署到GitHub Pages时，需在public文件夹创建404.html，内容与index.html完全一致，解决刷新页面出现404的问题（GitHub Pages静态服务器默认不支持SPA路由重写）。

内容的提问来源于stack exchange，提问作者Eric SsSnake