如何修复GitHub Pages的HTTP 404错误？React+Vite部署求助

1. 替换Vite的路径配置（弃用package.json的homepage） #

Vite不支持homepage字段，需要在web/vite.config.js（或.ts）里配置base，值要和GitHub Pages的访问路径匹配：

• 若为个人/组织主页仓库（仓库名格式：username.github.io），base设为'/'
• 若为项目仓库，base设为'/你的仓库名/'（比如你的仓库叫github-page，就写'/github-page/'）

示例配置：

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

export default defineConfig({
  plugins: [react()],
  base: '/github-page/' // 替换为你的实际仓库名
})

2. 修正GitHub Actions Workflow配置 #

确保Workflow里的步骤准确指向web目录的产物，示例完整配置（.github/workflows/deploy.yml）：

name: Deploy to GitHub Pages

on:
  push:
    branches: [ main ] # 替换为你的主分支名，比如master

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20 # 匹配你的项目Node版本

      - name: Install dependencies & build
        working-directory: ./web
        run: |
          npm install
          npm run build

      - name: Deploy to Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./web/dist # 明确指向web目录下的构建产物

3. 检查GitHub Pages仓库设置 #

• 进入仓库「Settings」→「Pages」
• 确认Source选择gh-pages分支，目录为/(root)
• 若之前有错误部署记录，先删除gh-pages分支，再重新推送代码触发Workflow

4. 修复React Router路由问题（若使用路由） #

GitHub Pages不支持SPA的history模式，刷新会导致404，需改用HashRouter：

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

function App() {
  return (
    <Router>
      {/* 你的路由配置 */}
    </Router>
  );
}

内容的提问来源于stack exchange，提问作者Victor Elias Ross Júnior