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/', // 注意：必须以 '/' 开头和结尾
// 其他配置...
}⚠️ 注意事项：
GInstall OneClick — 一键安装 GitHub 项目：规划、克隆、安装 Node 依赖、运行开发脚本。适用于想要获取 GitHubNode.js 项目的用户。
- base 值必须与 GitHub Pages 发布路径严格一致（区分大小写），你的仓库名为 3DPortfolio，故为 /3DPortfolio/；
- 若使用 gh-pages 分支或 docs 文件夹部署，路径逻辑不变，仍需匹配实际访问 URL 的前缀；
- 修改后务必重新构建：运行 npm run build（或 yarn build），确保生成的 dist/index.html 中 <script> 和 <link> 标签的 src/href 均自动添加了 /3DPortfolio/ 前缀。
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 配置失效。
? 补充建议：
- 使用 vite-plugin-gh-pages 可自动化处理 GitHub Pages 部署流程；
- 在 index.html 中添加 <base href="/3DPortfolio/">（不推荐，优先通过 vite.config.js 统一控制）；
- 部署后，打开浏览器开发者工具 → Network 标签页，查看 .js 和 .css 请求的实际 URL，验证是否已带正确前缀。
完成上述配置并重新部署后，资源加载路径将变为 https://www.php.cn/link/bfb542eee7ebaee0d567b99b69baf7ec3DPortfolio/assets/xxx.js，404 错误消失，网站正常渲染。
