vite 项目部署到 github pages 后仅显示空白页，根本原因通常是构建路径（base）配置错误，导致静态资源（js/css/图片）404 加载失败；本文提供可直接复用的配置方案与部署验证步骤。
vite 项目部署到 github pages 后仅显示空白页，根本原因通常是构建路径（base）配置错误，导致静态资源（js/css/图片）404 加载失败；本文提供可直接复用的配置方案与部署验证步骤。
当你使用 Vite 构建单页应用（SPA）并部署至 GitHub Pages 时，若访问 https://alperenkarslix.github.io/website/ 出现纯白页面、控制台报错 Failed to load resource: the server responded with a status of 404 ()（如 assets/index.abc123.js 未找到），这几乎可以确定是 vite.config.js 中 build.base 配置不匹配所致。
GitHub Pages 为用户仓库（如
✅ 正确解决方案：在 vite.config.js 中显式设置 build.base
根据你的仓库名 website 和部署目标 https://alperenkarslix.github.io/website/，推荐以下两种配置方式（任选其一）：
方式一：动态适配（推荐用于多环境）
|Git删除了文件，但还会在Git 仓库历史中遗留。 - 想要从 Git 历史移除敏感信息（密码、密钥、token、私钥） - 想要删除意外提交的大文件 - 想要重写 Git 历史、移除特定文件的所有痕迹 - 提到 "force push"、"重写 commit 历史" - 需要从所有分支、所有 tag 中删除某个文件
// vite.config.js
import { defineConfig } from 'vite'
export default defineConfig({
build: {
base: process.env.NODE_ENV === 'production'
? '/website/' // 注意末尾斜杠！必须与仓库名完全一致
: '/',
},
})
方式二：静态相对路径（更简单、兼容性更强）
// vite.config.js
import { defineConfig } from 'vite'
export default defineConfig({
build: {
base: './', // 所有资源路径转为相对路径（如 ./assets/index.js）
},
})
⚠️ 注意事项：
- 若选择方式一，请确保 './website/' 中的路径与你的 GitHub 仓库名严格一致（区分大小写、无多余字符）；
- base 值必须带末尾斜杠（如 /website/），否则路由和资源加载将异常；
- 使用 ./ 方式时，Vite 会生成相对路径引用，天然适配任意子路径，无需硬编码仓库名，适合快速验证或频繁变更仓库名的场景；
- 修改配置后，务必重新执行构建与部署流程：
npm run build # 生成新 build/ 目录 npm run deploy # 推送至 gh-pages 分支
此外，请确认 GitHub Pages 发布源已正确设置：
进入仓库 Settings → Pages → Branch → 选择 gh-pages 分支 + / (root) 目录（不是 /docs），保存后等待 1–2 分钟生效。
最后，部署完成后请直接访问 https://alperenkarslix.github.io/website/（注意末尾斜杠），并在浏览器开发者工具的 Network 标签页中刷新页面，检查 index.html 是否返回 200，以及所有 .js、.css 文件是否均成功加载（状态码 200）。若仍有 404，请检查 build/ 目录下生成的 index.html 中 <script> 和 <link> 标签的 src/href 属性是否已按预期添加了 ./ 前缀或 /website/ 前缀。</script>
通过精准配置 base，即可彻底解决 Vite + GitHub Pages 的空白页问题，让本地开发体验无缝延续至线上发布。
