部署React+Vite项目到GitHub出现404页面加载失败求助

问题核心 #

部署到GitHub Pages后页面无法显示，控制台提示「加载资源失败：服务器返回404状态（index.jsx[1]）」，本地开发、build预览都正常，但推送到GitHub后就出问题。

原因分析 #

1. Vite默认资源base路径是根目录，但GitHub Pages项目页（非自定义域名）的实际路径是https://用户名.github.io/仓库名/，根路径配置会导致资源找不到
2. GitHub Pages默认不识别Vite生成的dist目录，需要手动配置部署源指向dist
3. 若使用React Router的BrowserRouter，静态托管环境下刷新页面会触发404

分步解决方案 #

1. 配置Vite的base路径 #

修改vite.config.js，添加base字段，值为你的GitHub仓库名称（注意前后加斜杠）：

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

export default defineConfig({
  plugins: [react()],
  base: '/designo/' // 替换成你的GitHub仓库名称
})

2. 让GitHub Pages识别dist目录 #

两种方式可选：

方式一：用gh-pages包自动部署

• 安装依赖：

  npm install gh-pages --save-dev
  

• 修改package.json，新增两个部署脚本：

  {
    "scripts": {
      "dev": "vite",
      "build": "vite build",
      "predeploy": "npm run build",
      "deploy": "gh-pages -d dist",
      "lint": "eslint . --ext js,jsx --report-unused-disable-directives --max-warnings 0",
      "preview": "vite preview"
    }
  }
  

• 执行部署命令：

  npm run deploy
  

  命令会自动把dist目录内容推到gh-pages分支，之后去GitHub仓库「Settings → Pages」，选择gh-pages分支作为部署源即可。

方式二：用GitHub Actions自动构建部署

• 在仓库根目录创建.github/workflows/deploy.yml文件，内容如下：

  name: Deploy to GitHub Pages
  on:
    push:
      branches: [ main ] # 替换成你的主分支名称
  jobs:
    build-and-deploy:
      runs-on: ubuntu-latest
      steps:
        - name: Checkout code
          uses: actions/checkout@v4
        - name: Setup Node.js
          uses: actions/setup-node@v4
          with:
            node-version: '20'
        - name: Install dependencies
          run: npm install
        - name: Build project
          run: npm run build
        - name: Deploy to Pages
          uses: peaceiris/actions-gh-pages@v4
          with:
            github_token: ${{ secrets.GITHUB_TOKEN }}
            publish_dir: ./dist
  

• 提交该文件到GitHub，之后每次推送主分支都会自动构建并部署到Pages。

3. 修复React Router刷新404问题 #

如果项目使用react-router-dom的BrowserRouter，静态托管下刷新页面会404，直接换成HashRouter即可：

import { HashRouter as Router, Routes, Route } from 'react-router-dom'
import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App'

ReactDOM.createRoot(document.getElementById('root')).render(
  <React.StrictMode>
    <Router>
      <Routes>
        <Route path="/" element={<App />} />
        {/* 其他路由配置 */}
      </Routes>
    </Router>
  </React.StrictMode>
)

4. 本地验证 #

执行npm run build后，用vite preview预览生产环境打包后的内容，确认本地预览正常再推送到GitHub，避免无效操作。

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