Vite React项目部署GitHub Pages后空白页及404 CSS错误求助

1. 确认vite.config.js的base配置正确性 #

• 确保base的值是仓库的精确名称（GitHub仓库名区分大小写），比如仓库名为youfitnessApp，配置需严格匹配：

export default defineConfig({
  base: '/youfitnessApp/',
  // 其他配置项...
})

• 执行npm run build后，打开dist/index.html，检查CSS/JS等资源的引用路径是否为/youfitnessApp/assets/index-DfpUVyAv.css格式，若为相对路径或错误前缀，说明base配置未生效。

2. 检查package.json的部署配置 #

• 确认scripts中的deploy命令正确，标准配置如下：

"scripts": {
  "build": "vite build",
  "deploy": "gh-pages -d dist"
}

• 确保已安装gh-pages依赖：执行npm install gh-pages --save-dev，未安装会导致deploy命令失败。

3. 修正部署流程的错误步骤 #

• 你提到git push -u origin main报错，正确部署流程应为：
  1. 代码修改后，先提交源码到main分支：git add . && git commit -m "描述修改内容"，若push报错，先解决源码分支的冲突或权限问题（如仓库权限设置、本地与远程分支同步）。
  2. 执行npm run build生成最新的dist文件夹。
  3. 执行npm run deploy，该命令会自动将dist内容推送到gh-pages分支，无需手动推送main分支。

4. 确认react-router-dom的basename配置 #

• 使用CreateBrowserRouter时，basename必须与vite的base完全一致（包括开头的斜杠）：

const router = createBrowserRouter([
  // 路由规则配置...
], {
  basename: '/youfitnessApp/'
});

• 页面跳转必须使用Link组件，禁止直接使用原生<a>标签，避免触发页面刷新导致路径错误。

5. 检查GitHub Pages的设置 #

• 进入GitHub仓库的Settings -> Pages页面：
  • 确认Source选项为Deploy from a branch，Branch选择gh-pages和/root。
  • 等待部署完成（通常需要1-5分钟），之后用Ctrl+Shift+R强制刷新浏览器，清除缓存后再访问。

6. 验证dist文件夹的内容 #

• 执行npm run build后，检查dist文件夹是否包含完整的assets目录和index.html，且index.html中所有资源路径均带有正确的仓库名前缀。若路径异常，排查vite.config.js是否存在语法错误或未正确导出配置。

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