Vite React项目部署GitHub失败：dist文件未上传致404错误

部署失败核心原因有两个：

1. 构建生成的dist文件夹未被正确上传到GitHub，导致GitHub Pages找不到静态资源
2. vite.config.js中的base配置与自定义域名的根路径不匹配，引发资源路径错误

1. 确保构建产物能被Git追踪并上传 #

• 检查项目根目录的.gitignore文件，删除其中的dist条目（如果存在），让Git可以追踪该文件夹
• 本地执行构建命令生成最新产物：

  npm run build
  

• 将dist文件夹提交并推送到GitHub：

  git add dist
  git commit -m "Add build artifacts"
  git push
  

2. 修正Vite的base路径配置 #

由于使用自定义域名，站点部署在域名根路径下，需修改vite.config.js：

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

export default defineConfig({
  base: '/', // 自定义域名使用根路径，无需填写仓库名
  plugins: [react()],
})

修改后重新执行npm run build，更新dist内的资源路径。

3. 配置自定义域名 #

• 在项目根目录创建CNAME文件，内容为你的自定义域名（例如your-custom-domain.com），将该文件提交到GitHub
• 进入GitHub仓库的「Settings」→「Pages」：
  • 在「Custom domain」输入框填写你的域名
  • 勾选「Enforce HTTPS」（若域名支持HTTPS）
  • 确认部署分支与文件夹：若用main分支部署，选择「/dist」作为部署目录；若用gh-pages分支，确保该分支包含dist的完整内容

4. 用gh-pages包简化部署流程（可选） #

若手动管理dist繁琐，可借助gh-pages自动部署：

• 安装依赖：

  npm install gh-pages --save-dev
  

• 在package.json的scripts中添加：

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

• 执行部署命令：

  npm run deploy
  

该命令会自动构建产物，并将dist内容推送到gh-pages分支，GitHub Pages会自动从该分支部署站点。

部署完成后访问自定义域名，检查控制台是否还有404错误。若资源加载正常，页面即可正常显示。

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