React Router Dom部署GitHub Pages后仅首页可用问题排查

本地环境使用React Router Dom完全正常，首次部署到GitHub Pages也能正常运行，但修复部分Bug重新部署后，只有首页可以访问，其他所有路由都失效。试过切换为HashRouter（能正常工作，但路径会带/#/），也给BrowserRouter设置了basename="/"，问题依然存在。

App.js路由配置 #

return (
  <BrowserRouter basename="/">
    <Routes>
      <Route exact path="/" element={<Home />} />
      <Route exact path="/home" element={<Home />} />
      <Route exact path="/header" element={<div><Header links="/"/><Me /><Footer /></div>} />
      <Route exact path="/me" element={<div><Header links="/"/><Me /><Footer /></div>} />
      <Route exact path="/About" element={<div><Header links="/"/> <About /> <Footer /></div>} />
      <Route exact path="/projects" element={<div><Header links="/"/> <Projects /> <Footer /></div>} />
      <Route exact path="/skills" element={<div><Header links="/"/> <Skills /> <Footer /></div>} />
      <Route exact path="/contact" element={<div><Header links="/"/> <Contact /> <Footer /></div>} />
      <Route path="*" element={<ErrorPage />} />
    </Routes>
  </BrowserRouter>
);

package.json配置 #

{
  "homepage": "http://ayazvefa.dev/",
  "name": "vefa-ayaz",
  "version": "1.0.0",
  "private": true,
  "dependencies": {
    "@testing-library/jest-dom": "^5.16.5",
    "@testing-library/react": "^13.4.0",
    "@testing-library/user-event": "^13.5.0",
    "aos": "^3.0.0-beta.6",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "react-router-dom": "^6.9.0",
    "react-script-tag": "^1.1.2",
    "react-scripts": "5.0.1",
    "typed.js": "^2.0.132",
    "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"
  }
}

问题原因及解决方案 #

核心原因 #

GitHub Pages是静态文件托管服务，当直接访问非首页路由（比如/projects）时，服务器会尝试寻找对应路径的物理文件，找不到就返回404。而BrowserRouter依赖服务器将所有路由请求转发到index.html，GitHub Pages默认不支持这个规则。

首次部署正常大概率是因为当时仅通过页面内的前端导航跳转路由，没有直接刷新或手动输入非首页路径，修复Bug后才触发了直接访问路由的场景，暴露了问题。

修复方案 #

方案一：用_redirects文件实现路由转发（无哈希路径，推荐）

如果使用了自定义域名，在项目的public目录下创建_redirects文件，内容如下：

/* /index.html 200

这个文件会告诉GitHub Pages将所有路由请求都转发到index.html，BrowserRouter就能正常工作，路径也不会带/#/。部署时这个文件会被自动打包到build目录。

方案二：添加404回退配合HashRouter

在public目录下创建404.html，内容和index.html完全一致，然后在index.html的<head>中加入以下脚本：

<script>
  if (window.location.pathname !== '/') {
    window.location.replace('/#' + window.location.pathname);
  }
</script>

同时将BrowserRouter替换为HashRouter，这种方法能保证路由正常，但路径会带有/#/。

额外检查点

• 统一路由路径的大小写：比如路由里的/About（大写A），如果导航链接用了/about（小写）会触发404，建议全部改为小写路径，避免大小写敏感问题。
• 确认package.json中的homepage配置正确，当前配置符合自定义域名的要求。

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