本文详解 Vite 项目部署到 GitHub Pages 时出现空白页的根本原因（路径配置错误），并提供两种可靠解决方案：动态设置 base 路径或统一使用相对路径 './'，配合 gh-pages 自动发布流程，确保资源正确加载。
本文详解 vite 项目部署到 github pages 时出现空白页的根本原因（路径配置错误），并提供两种可靠解决方案：动态设置 `base` 路径或统一使用相对路径 `'./'`，配合 `gh-pages` 自动发布流程，确保资源正确加载。
当你将基于 Vite 的前端项目部署至 GitHub Pages 后仅显示空白页（index.html 加载成功但 JS/CSS 404），这几乎总是由静态资源路径解析失败导致——Vite 默认以根路径 / 为基准生成资源引用（如 <script src="/assets/index.abc123.js">），而 GitHub Pages 的用户仓库页面实际托管在子路径下（例如 https://alperenkarslix.github.io/website/），浏览器会错误地向 https://alperenkarslix.github.io/assets/... 发起请求，而非正确的 https://alperenkarslix.github.io/website/assets/...。</script>
✅ 正确配置 Vite 的 base 选项
关键在于显式声明构建产物的公共基础路径。打开 vite.config.js，在 build 配置中设置 base：
方案一：使用相对路径（推荐，简洁可靠）
// vite.config.js
import { defineConfig } from 'vite'
export default defineConfig({
build: {
base: './', // 所有资源路径转为相对路径（如 ./assets/index.js）
}
})✅ 优势：无需硬编码仓库名，适配任意子路径（/repo/、/project-v2/ 等），本地预览与线上环境行为一致。
方案二：动态匹配 GitHub Pages 路径（需精确匹配仓库名）
// vite.config.js
import { defineConfig } from 'vite'
export default defineConfig({
build: {
base: process.env.NODE_ENV === 'production'
? '/website/' // 替换为你的仓库名（注意结尾斜杠！）
: '/',
}
})⚠️ 注意：base 值必须与 GitHub Pages 实际 URL 的路径部分完全一致（例如 https://user.github.io/repo-name/ → base: '/repo-name/'），且必须包含开头和结尾的斜杠。
? 部署流程验证（确保无遗漏）
-
确认 package.json 配置正确：
{ "homepage": "https://alperenkarslix.github.io/website", "scripts": { "build": "vite build", "predeploy": "npm run build", "deploy": "gh-pages -d dist" // 注意：Vite 默认输出目录为 `dist`，非 `build` } }? 重要：Vite 构建默认输出到 dist/ 目录（除非你自定义了 build.outDir）。若 package.json 中 deploy 命令仍写 -d build，会导致发布空目录。请统一改为 -d dist。
-
执行部署：
npm run deploy
成功后，检查 gh-pages 分支是否包含 index.html 及 assets/ 等内容，并确认 index.html 中的 <script> 和 <link> 标签路径以 ./ 开头（方案一）或 /website/ 开头（方案二）。</script>
-
访问验证 URL：
- 最终地址应为：https://alperenkarslix.github.io/website/
- 浏览器开发者工具（Network 标签页）中检查所有 .js、.css 文件状态码是否为 200；若仍有 404，请回查 base 配置与实际 URL 路径是否严格匹配。
? 总结与最佳实践
- 首选 base: './'：避免路径硬编码，提升可移植性，尤其适合多环境部署；
- 切勿忽略 homepage 字段：它影响 React/Vue 路由的 basename（如使用 createBrowserRouter），但 Vite 本身不读取该字段，仅 base 配置生效；
- 始终验证构建产物：npm run build 后手动打开 dist/index.html，用浏览器直接打开（file://），确认本地可正常运行；
- GitHub Pages 发布源设置：进入仓库 Settings → Pages → Branch，确保 Source 设置为 gh-pages branch 且 /(root) 目录（非 /docs）。
遵循以上配置，即可彻底解决 Vite 项目在 GitHub Pages 上的空白页问题，让静态站点稳定、高效地对外服务。
