将React(Vite)应用部署到GitHub Pages时遇404错误求助

以下是针对你遇到问题的具体排查和修复步骤：

1. 确认Vite配置文件的base设置 #

打开项目根目录下的vite.config.js或vite.config.ts，确保base字段与你的GitHub仓库名称完全一致，格式为/仓库名/（注意前后必须带斜杠）。示例：

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

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

注意：不要仅依赖package.json中的配置，Vite的base设置必须在这个配置文件中定义才会生效。

2. 校验package.json的部署脚本 #

确保package.json中的scripts包含正确的预部署和部署命令，且指向Vite的默认打包输出目录dist：

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "predeploy": "npm run build",
    "deploy": "gh-pages -d dist"
  }
}

• predeploy会在deploy前自动执行打包，确保部署的是最新构建产物
• gh-pages -d dist指定将dist目录的内容推送到GitHub的gh-pages分支

3. 检查项目内资源引用方式 #

图片资源 #

不要使用绝对路径引用图片，改用相对路径或Vite的模块导入方式：

• 错误示例：<img src="/src/assets/logo.png" />
• 正确示例1（相对路径）：<img src="./assets/logo.png" />
• 正确示例2（模块导入）：

  import logo from './assets/logo.png'
  // 组件内使用
  <img src={logo} alt="logo" />
  

CSS中的资源 #

CSS里的背景图等资源同样要用相对路径：

• 错误示例：background: url('/src/assets/bg.jpg')
• 正确示例：background: url('./assets/bg.jpg')

4. 确认GitHub Pages的部署配置 #

登录你的GitHub仓库，进入Settings -> Pages：

• 检查Source选项是否选择了gh-pages分支，且目录为/root（不要选/docs目录）
• 如果之前配置过其他分支或目录，修改后点击Save重新触发部署

5. 清除本地缓存并重新部署 #

执行以下命令清理本地旧的gh-pages分支并重新部署：

# 删除本地gh-pages分支
git branch -D gh-pages
# 重新执行部署
npm run deploy

部署完成后，等待1-2分钟让GitHub Pages更新，再刷新页面查看。

6. 路由相关问题（若使用React Router） #

如果你的项目使用了React Router的BrowserRouter，GitHub Pages不支持这种路由模式（需要服务器配置URL重写），会导致页面空白或路由跳转404。解决方法是改用HashRouter：

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

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

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