Vite部署GitHubPages白屏解决指南

Vite项目部署到GitHub Pages后频繁白屏？根本原因在于默认的根路径配置与GitHub Pages子路径（如username.github.io/repo-name）不兼容，导致JS/CSS等静态资源404加载失败；本文直击痛点，详解两种可靠解决方案——推荐使用`build.base: './'`启用相对路径（简单、鲁棒、免维护），或精准配置`build.base: '/repo-name/'`配合gh-pages分支发布，并同步梳理homepage字段设置、构建清理、部署脚本及GitHub Pages源分支验证等关键步骤，附常见错误排查清单，助你一次性彻底解决白屏难题，让Vite应用稳稳上线。

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://alperenkarslix.github.io/website/），而 Vite 默认构建产物假设所有资源都从域名根目录加载（即