Vite+React项目部署至GitHub Pages出现404白屏问题求助

问题概况 #

项目从Create React App迁移至Vite后本地运行正常，但部署到GitHub Pages页面空白，控制台提示资源加载404。

当前配置文件 #

package.json #

{
  "name": "upgrade",
  "private": true,
  "version": "0.0.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "lint": "eslint . --ext js,jsx --report-unused-disable-directives --max-warnings 0",
    "preview": "vite preview"
  },
  "dependencies": {
    "macro-css": "^1.0.5",
    "node-sass": "^9.0.0",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "react-router-dom": "^6.15.0"
  },
  "devDependencies": {
    "@types/react": "^18.2.15",
    "@types/react-dom": "^18.2.7",
    "@vitejs/plugin-react": "^4.0.3",
    "eslint": "^8.45.0",
    "eslint-plugin-react": "^7.32.2",
    "eslint-plugin-react-hooks": "^4.6.0",
    "eslint-plugin-react-refresh": "^0.4.3",
    "gh-pages": "^6.0.0",
    "sass": "^1.66.1",
    "vite": "^4.4.5"
  }
}

vite.config.js #

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

export default defineConfig({
  plugins: [react()],
  base: "/upgrade/"
})

分步解决方案 #

1. 添加部署脚本 #

在package.json的scripts字段中补充两个命令：

"predeploy": "npm run build",
"deploy": "gh-pages -d dist"

• predeploy会自动在部署前执行构建，保证上传的是最新编译产物
• deploy负责将dist目录内容推送到gh-pages分支

2. 确认GitHub Pages仓库配置 #

• 打开GitHub仓库的Settings > Pages页面
• 检查Source选项是否设置为gh-pages分支，根目录（/root）
• 若之前配置错误，修改后等待GitHub重新部署

3. 修复React Router路由问题 #

如果项目使用BrowserRouter，GitHub Pages静态环境不支持前端路由的刷新跳转，需做以下调整：

• 方案一：改用HashRouter

  import { HashRouter as Router, Routes, Route } from 'react-router-dom';
  
  function App() {
    return (
      <Router>
        <Routes>
          {/* 你的路由规则 */}
        </Routes>
      </Router>
    );
  }
  

• 方案二：保留BrowserRouter，添加重定向配置
  1. 在vite.config.js中启用history fallback：

     export default defineConfig({
       plugins: [react()],
       base: "/upgrade/",
       server: {
         historyApiFallback: true
       }
     })
     

  2. 在项目public目录下创建_redirects文件，内容为：

     /* /index.html 200
     

4. 验证构建资源路径 #

执行npm run build后，打开dist/index.html，确认所有资源的引用路径前缀为/upgrade/（与vite.config.js中的base一致），例如：

<script type="module" src="/upgrade/assets/index.xxxx.js"></script>

若路径错误，检查base配置是否与GitHub仓库名称完全匹配。

5. 清理缓存重新部署 #

• 删除本地dist目录和node_modules/.cache文件夹
• 重新执行npm run deploy
• 在GitHub Pages页面强制刷新浏览器（Ctrl+F5），清除缓存

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