解决 Vite + React 项目部署 GitHub Pages 的完整指南：从 404 到成功部署
问题背景
在将 Vite + React 项目部署到 GitHub Pages 时，很多开发者会遇到一个常见问题：页面显示 404 错误，控制台报错找不到 main.jsx 文件。错误信息通常如下：
text
GET https://username.github.io/repo/src/main.jsx 404 Not Found
这个问题困扰了很多开发者，本文将提供完整的解决方案
问题根源分析
错误原因
路径配置错误：GitHub Pages 使用项目名称作为路径前缀
Jekyll 干扰：GitHub 默认使用 Jekyll 构建，会忽略某些文件
构建流程缺失：直接部署源代码而非构建后的静态文件
核心理解
GitHub Pages 只能托管静态文件，无法直接运行 React/JSX 源代码。必须通过构建工具（如 Vite）生成生产版本。
完整解决方案
第一步：项目配置修正
1. 修改 vite.config.js
javascript
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'export default defineConfig({plugins: [react()],base: '/your-repo-name/', // 重要：与仓库名称一致build: {outDir: 'dist',emptyOutDir: true}
})2. 清理 index.html
html
<!DOCTYPE html> <html lang="zh-CN"><head><meta charset="UTF-8" /><link rel="icon" type="image/svg+xml" href="/vite.svg" /><meta name="viewport" content="width=device-width, initial-scale=1.0" /><title>你的应用标题</title></head><body><div id="root"></div><!-- 删除手动引入的 script 标签 --></body> </html>
关键点：让 Vite 在构建时自动注入资源路径。
3. 配置 package.json
json
{"scripts": {"dev": "vite","build": "vite build","preview": "vite preview","predeploy": "npm run build","deploy": "gh-pages -d dist"},"homepage": "https://username.github.io/repo-name"
}第二步：禁用 Jekyll
在 public 目录创建 .nojekyll 文件：
bash
# 在项目根目录执行 touch public/.nojekyll
这个空文件告诉 GitHub Pages 不要使用 Jekyll 处理你的项目。
第三步：设置 GitHub Actions 自动化部署
创建 .github/workflows/deploy.yml：
yaml
name: Deploy Vite React App to GitHub Pageson:push:branches: [ main ]workflow_dispatch:permissions:contents: readpages: writeid-token: writeconcurrency:group: "pages"cancel-in-progress: falsejobs:build:runs-on: ubuntu-lateststeps:- name: Checkoutuses: actions/checkout@v4- name: Setup Node.jsuses: actions/setup-node@v4with:node-version: '18'cache: 'npm'- name: Install dependenciesrun: npm install- name: Build projectrun: npm run build- name: Setup Pagesuses: actions/configure-pages@v4- name: Upload artifactuses: actions/upload-pages-artifact@v3with:path: ./distdeploy:environment:name: github-pagesurl: ${{ steps.deployment.outputs.page_url }}runs-on: ubuntu-latestneeds: buildsteps:- name: Deploy to GitHub Pagesid: deploymentuses: actions/deploy-pages@v4第四步：本地测试验证
在部署前进行本地测试：
bash
# 安装依赖 npm install# 构建项目 npm run build# 预览构建结果 npm run preview
访问 http://localhost:4173 确认应用正常工作。
第五步：部署和验证
1. 提交代码触发部署
bash
git add . git commit -m "feat: deploy to GitHub Pages" git push origin main
2. 检查部署状态
访问 GitHub 仓库 → Actions 查看部署进度
部署成功后访问：
https://username.github.io/repo-name
3. 验证部署成功
检查构建后的 dist/index.html 应该包含正确的资源路径：
html
<script type="module" crossorigin src="/repo-name/assets/index-xxxxxx.js"></script>
常见问题排查
问题1：仍然报 404 错误
解决方案：
检查仓库名称是否与配置一致
清除浏览器缓存（Ctrl+F5）
访问时添加版本参数：
?v=2
问题2：资源加载失败
解决方案：
确认
vite.config.js中的base配置正确检查构建产物是否完整
问题3：GitHub Actions 构建失败
解决方案：
查看 Actions 日志定位错误
确保
package.json中的脚本正确
问题4：样式或图片不显示
解决方案：
使用相对路径引用资源
检查
public目录中的静态资源
最佳实践建议
1. 路径配置
始终使用相对路径或 Vite 的路径别名
避免硬编码绝对路径
2. 环境区分
javascript
// vite.config.js
export default defineConfig({base: process.env.NODE_ENV === 'production' ? '/repo-name/' : '/',
})3. 缓存策略
为静态资源添加版本哈希
使用合适的缓存头配置
4. 监控和回滚
设置健康检查端点
保留之前的部署版本以便快速回滚
总结
成功部署 Vite + React 项目到 GitHub Pages 的关键点：
正确的 base 路径配置
禁用 Jekyll 处理
使用 GitHub Actions 自动化构建
确保构建产物路径正确
彻底的本地测试
通过本文的步骤，你应该能够解决常见的 404 问题，并建立稳定的自动化部署流程。记住，部署前一定要在本地进行充分测试，这样可以节省大量的排查时间。
提示：如果遇到其他问题，欢迎在评论区留言，我会及时回复并提供解决方案。