React项目部署至GitHub Pages遇Unexpected Application Error! 404错误

1. 恢复正确的homepage配置 #

不要删除homepage字段，必须填写与仓库匹配的GitHub Pages访问地址，格式为：

"homepage": "https://<你的GitHub用户名>.github.io/<你的仓库名称>"

例如你的仓库名为typing-training-app，就填：

"homepage": "https://*****.github.io/typing-training-app"

（替换*****为你的GitHub用户名，确保地址和仓库实际访问路径完全一致）

2. 修复React Router导致的404问题 #

你使用了react-router-dom，而GitHub Pages作为静态托管服务，默认不支持单页应用的BrowserRouter路由逻辑——直接刷新子路由或输入子路由访问时，会返回404。有两种解决方式：

方式一：改用HashRouter #

修改路由根组件，将BrowserRouter替换为HashRouter：

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

function App() {
  return (
    <Router>
      <Routes>
        {/* 你的路由规则 */}
      </Routes>
    </Router>
  );
}

HashRouter会在URL中添加#（比如https://*****.github.io/typing-training-app/#/about），这种方式无需额外配置，兼容性最强。

方式二：保留BrowserRouter并添加404重定向文件 #

如果不想使用HashRouter，需在项目的public目录下创建404.html文件，内容完全复制public/index.html的内容。

重新构建部署后，当访问不存在的路径时，GitHub Pages会返回404.html，由React Router接管路由逻辑。

3. 重新部署并检查仓库设置 #

• 执行构建和部署命令：

npm run build
npm run deploy

• 进入GitHub仓库的Settings -> Pages页面，确认：
  • 部署分支为gh-pages
  • 部署目录为/root
  • 等待部署完成后刷新页面（可能需要等待几分钟缓存更新）

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