问题背景
在将 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 Pages
on:
push:
branches: [ main ]
workflow_dispatch:
permissions:
contents: read
pages: write
id-token: write
concurrency:
group: "pages"
cancel-in-progress: false
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '18'
cache: 'npm'
- name: Install dependencies
run: npm install
- name: Build project
run: npm run build
- name: Setup Pages
uses: actions/configure-pages@v4
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: ./dist
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
needs: build
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: 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 main2. 检查部署状态
-
访问 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 问题，并建立稳定的自动化部署流程。记住，部署前一定要在本地进行充分测试，这样可以节省大量的排查时间。
提示：如果遇到其他问题，欢迎在评论区留言，我会及时回复并提供解决方案。