Vite React应用的HashRouter在GitHub Pages中无法正常工作怎么办？

• 配置Vite的base路径
  GitHub Pages部署后，应用根路径为https://<username>.github.io/<repo-name>/，而非根域名。需在vite.config.js中设置正确base：

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  base: '/your-repository-name/' // 替换为你的仓库名称
});

打包后资源路径会自动添加前缀，避免404错误。

• 统一路由路径大小写
  GitHub Pages文件系统区分大小写，若路由/HeroesPage对应的文件命名或跳转链接为小写，会导致匹配失败。建议将路由改为全小写（如/heroespage），同时确保跳转链接与路由配置完全一致。

• 使用正确的跳转方式
  必须用React Router的<Link>组件跳转，禁止使用原生<a>标签：

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

// 正确写法
<Link to="/HeroesPage">英雄页面</Link>

// 错误写法（刷新页面会破坏哈希路由）
<a href="/HeroesPage">英雄页面</a>

• 简化HashRouter导入
  代码中HashRouter as HashRouter属于冗余写法，直接导入即可：

import { HashRouter, Routes, Route } from 'react-router-dom';

• 查看浏览器控制台错误
  部署后打开浏览器开发者工具（F12）：

  • Console面板的报错会直接提示路由匹配、资源加载等问题
  • Network面板若出现404请求，说明资源路径配置错误，回到第一步检查base设置

• 确认GitHub Pages部署配置
  在仓库Settings > Pages中，确保：

  • 部署分支为gh-pages（或存放打包产物的分支）
  • 部署目录选择/dist（Vite打包后的产物目录）

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