如何解决 GitHub Pages 部署后 Vite 项目返回 404 的问题-html教程-PHP中文网

vite 项目本地运行正常但部署到 github pages 后出现空白页和 404 错误，根本原因是静态资源路径未适配子路径，需在 vite.config.js 中正确配置 base 选项并遵循 github pages 静态部署规范。

vite 项目本地运行正常但部署到 github pages 后出现空白页和 404 错误，根本原因是静态资源路径未适配子路径，需在 vite.config.js 中正确配置 base 选项并遵循 github pages 静态部署规范。

当你将基于 Vite 构建的个人网站（如你的 3DPortfolio）部署到 GitHub Pages 时，项目并非托管在根域名（如 https://www.php.cn/link/bfb542eee7ebaee0d567b99b69baf7ec），而是位于子路径下：https://www.php.cn/link/bfb542eee7ebaee0d567b99b69baf7ec3DPortfolio/。Vite 默认将所有资源路径（如 JS、CSS、图片）解析为根路径（/assets/xxx.js），导致浏览器尝试从 https://www.php.cn/link/bfb542eee7ebaee0d567b99b69baf7ecassets/... 加载资源——该路径不存在，因而返回 404，页面白屏。

✅ 正确解决方案分两步：

1. 配置 Vite 的 base 选项
在项目根目录的 vite.config.js 中，显式设置 base 为仓库名（即 GitHub Pages 子路径）：

// vite.config.js
export default {
  base: '/3DPortfolio/', // 注意：必须以 '/' 开头和结尾
  // 其他配置...
}

⚠️ 注意事项：

Evez Github Manager

在 OpenClaw 中管理 GitHub 仓库、Pull Request、Issue 与工作流。适用于审查 PR、管理 Issue、自动化 GitHub Actions、同步仓库等场景。

下载

base 值必须与 GitHub Pages 发布路径严格一致（区分大小写），你的仓库名为 3DPortfolio，故为 /3DPortfolio/；
若使用 gh-pages 分支或 docs 文件夹部署，路径逻辑不变，仍需匹配实际访问 URL 的前缀；
修改后务必重新构建：运行 npm run build（或 yarn build），确保生成的 dist/index.html 中 <script> 和 <link> 标签的 src/href 均自动添加了 /3DPortfolio/ 前缀。</script>

2. 确保 GitHub Pages 源正确设置
进入仓库 Settings → Pages → Source，确认：

构建和部署方式为 GitHub Actions（推荐）或 Deploy from a branch；
若选后者，请指定 gh-pages 分支的 / (root) 目录（或 docs 文件夹）；
✅ 关键检查：访问 https://www.php.cn/link/bfb542eee7ebaee0d567b99b69baf7ec3DPortfolio/ 时，浏览器地址栏 URL 必须以 /3DPortfolio/ 结尾（而非重定向到 /），否则 base 配置失效。

? 补充建议：