Vite 项目部署到 GitHub Pages 后出现空白页，通常是因构建路径（base）未适配子路径导致资源 404；本文详解通过 vite.config.js 设置 build.base 为 './' 或动态路径，并配合 homepage 字段完成兼容部署。
vue/vite 项目部署到 github pages 后出现空白页，通常是因构建路径（base）未适配子路径导致资源 404；本文详解通过 vite.config.js 设置 build.base 为 './' 或动态路径，并配合 homepage 字段完成兼容部署。
GitHub Pages 默认将用户仓库托管在 https://
根本解法是让 Vite 在构建时生成相对路径或正确前缀的绝对路径。推荐在 vite.config.js 中显式配置 build.base：
// vite.config.js
import { defineConfig } from 'vite'
export default defineConfig({
build: {
base: './', // ✅ 关键：使用相对路径，所有资源引用变为 ./assets/...
// 其他配置（如 rollupOptions、minify 等）
}
})该配置使生成的 index.html 中脚本引入形如：
<script type="module" src="./assets/index.abc123.js"></script>
浏览器会基于当前 HTML 文件位置（/website/）自动解析相对路径，精准定位资源。
⚠️ 注意事项：
GitHub操作助手下载用大白话操作当前项目的 Git/GitHub——配置 GitHub（装 gh CLI + 登录 + 建仓库）、备份、拉取下载、查询历史、回滚代码、管理分支。当用户用日常语言表达 git 意图时触发（例如"git备份一下""git下载项目""git拉下来""git看看我改了啥""git回退到上一个版本""git新建个分支搞新功能""git合并到主分支""git
- 若你使用 homepage 字段（如 "homepage": "https://alperenkarslix.github.io/website/"），Vite 不会自动读取它设置 base —— 这与 Create React App 不同。必须手动在 vite.config.js 中配置。
- base: '/' 仅适用于用户主页（username.github.io），不适用于项目页（username.github.io/repo-name）。
- 动态写法（兼容本地开发与生产）：
base: process.env.NODE_ENV === 'production' ? '/website/' // 替换为你的仓库名 : '/'但需确保仓库名拼写完全一致（区分大小写），且无额外路径层级。
同时，请确认你的 GitHub Pages 发布源已正确设置：
- 进入仓库 Settings → Pages → Branch → 选择 gh-pages 分支 + / (root) 目录（若 gh-pages 分支中文件位于根目录）；
- 确保 npm run deploy 成功推送了 build/ 目录下的全部内容（含 index.html, assets/, favicon.ico 等）至 gh-pages 分支根路径。
最后验证：访问 https://alperenkarslix.github.io/website/（结尾带斜杠），打开浏览器开发者工具 → Network 标签页，刷新页面，检查所有 .js / .css 请求是否返回 200。若仍有 404，请检查 build/ 目录结构是否扁平（无嵌套 build/build/），并确认 vite.config.js 已被 Vite 正确加载（可临时添加 console.log('config loaded') 验证）。
总结：Vite + GitHub Pages 白屏问题本质是路径解析错位，核心只需一行配置 build.base: './'，无需修改 package.json 的 homepage（它仅用于某些插件提示，不影响构建输出），即可实现开箱即用的子路径静态部署。
