React-Vite部署GitHub Pages后空白页及资源404问题求助

1. 配置Vite基础路径（核心修复） #

GitHub Pages的资源路径规则取决于站点类型：

• 若为用户/组织主页站点（仓库名必须是 <你的GitHub用户名>.github.io），将Vite的base设为'/'；
• 若为项目站点（仓库名非上述格式），base必须设为'/<你的仓库名>/'（例如仓库名为my-react-app则写'/my-react-app/'）。

修改vite.config.js或vite.config.ts：

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

export default defineConfig({
  plugins: [react()],
  base: '/<你的仓库名>/', // 替换为实际仓库名，主页站点则用'/'
})

2. 配置部署脚本与依赖 #

1. 安装gh-pages工具（用于将dist目录内容推送到GitHub Pages专用分支）：

npm install gh-pages --save-dev

2. 在package.json中补充配置：

{
  "homepage": "https://cazbella.github.io/<你的仓库名>/", // 主页站点则写"https://cazbella.github.io/"
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
    "deploy": "gh-pages -d dist"
  }
}

3. 确认GitHub Pages部署设置 #

进入你的GitHub仓库 → Settings → Pages：

• 在Build and deployment区域，Source选择Deploy from a branch；
• Branch选择gh-pages分支，目录选择/root，保存设置。

4. 重新部署验证 #

1. 执行生产构建：

npm run build

2. 部署到GitHub Pages：

npm run deploy

3. 检查dist目录下的index.html，确认资源引用路径与base配置一致（例如/仓库名/assets/xxx.js）；
4. 访问站点时强制刷新页面（Ctrl+F5），清除浏览器缓存。

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