vite 项目部署到 github pages 后出现白屏，通常因资源路径错误导致静态文件（js/css）404；核心解决方法是在 vite.config.js 中正确配置 build.base，适配 github pages 的子路径部署结构。
vite 项目部署到 github pages 后出现白屏，通常因资源路径错误导致静态文件（js/css）404；核心解决方法是在 vite.config.js 中正确配置 build.base，适配 github pages 的子路径部署结构。
当你将基于 Vite 的前端项目（如 React、Vue 或纯 HTML/JS 项目）部署至 GitHub Pages，尤其是以用户/组织页（username.github.io/repo-name）形式发布时，默认的根路径 / 会失效——因为 GitHub Pages 实际将你的站点托管在子路径下（例如 https://www.php.cn/link/78f58a8b3761d55a831805c9a278fc45），而 Vite 默认构建产物假设所有资源都从域名根目录加载（即 <script src="/assets/index.xxxx.js">），导致浏览器尝试请求 https://alperenkarslix.github.io/assets/...（404），最终页面空白。</script>
✅ 正确配置 vite.config.js
你需要显式设置 build.base，使其与 GitHub Pages 的实际访问路径匹配。推荐两种方案：
方案一：使用相对路径（最简单、兼容性最佳）
// vite.config.js
import { defineConfig } from 'vite'
export default defineConfig({
build: {
base: './', // ✅ 关键：生成相对路径引用，如 src="./assets/index.js"
}
})该配置让 Vite 在构建时输出所有资源链接为相对路径（./assets/xxx.js），无论部署在根域还是子路径（如 /website/）均可正常解析。
方案二：显式指定仓库名（适用于固定路径场景）
// vite.config.js
import { defineConfig } from 'vite'
export default defineConfig({
build: {
base: '/website/', // ✅ 替换为你的仓库名（注意末尾斜杠！）
}
})此方式生成绝对路径引用（src="/website/assets/xxx.js"），需确保 GitHub Pages 发布源设置为 gh-pages 分支且发布路径为 / (root)，同时访问地址严格匹配 https://
⚠️ 注意：若使用方案二但未在 GitHub Settings → Pages → Build and deployment 中将 Source 设为 gh-pages branch，或误设为 main /docs folder，仍会导致路径错乱。
? 完整部署流程验证（关键步骤）
-
确保 package.json 中 homepage 字段与实际 GitHub Pages 地址一致（对子路径项目应设为子路径）：
"homepage": "https://alperenkarslix.github.io/website"
✅ 此字段虽非 Vite 构建必需，但部分框架（如 Create React App）依赖它；Vite 项目中建议保持与 base 逻辑一致，避免混淆。
更新 vite.config.js 并保存（推荐先用 base: './'）。
-
清理并重新构建：
rm -rf dist build npm run build # 默认输出到 dist/，若自定义请同步调整 deploy 命令
-
执行部署（确保 gh-pages 已安装且 deploy 脚本指向正确目录）：
"scripts": { "deploy": "gh-pages -d dist" // ✅ 注意：此处应与 build 输出目录一致（默认为 dist） }运行：
npm run deploy
-
登录 GitHub → 仓库 Settings → Pages → 检查：
- Source: gh-pages branch（不是 main 或 docs folder）
- Branch: gh-pages，/(root) folder（无需更改）
访问 https://www.php.cn/link/78f58a8b3761d55a831805c9a278fc45（注意末尾斜杠）——此时资源应正常加载，页面不再白屏。
? 常见误区与排查清单
- ❌ 错误：base: '/' + 部署到子路径 → 所有资源请求 404
- ❌ 错误：base: '/website'（缺末尾 /）→ 浏览器解析为 https://.../websiteassets/...
- ❌ 错误：gh-pages -d build 但 vite build 输出到 dist/ → 静态文件未上传
- ❌ 错误：GitHub Pages 设置为 main /docs folder，但实际构建产物在 gh-pages 分支 → 内容不生效
- ✅ 提示：打开浏览器 DevTools → Network 标签页，刷新页面，观察 .js/.css 请求是否返回 404；若 404，说明 base 配置错误或路径不匹配。
? 总结
GitHub Pages 白屏的本质是前端路由与静态资源路径的上下文错位。Vite 默认为根部署设计，而 GitHub Pages 子路径场景需主动适配。build.base: './' 是最鲁棒的选择——它不依赖环境变量、无需硬编码仓库名、天然支持本地预览与多环境部署。配合正确的分支发布设置和构建脚本，即可一劳永逸解决白屏问题。
? 参考文档：Vite 官方部署指南｜GitHub Pages 发布源配置
