使用Vite.js部署GitHub Pages时路径异常及文件嵌套问题求助

问题背景 #

使用Vite搭建的项目，通过gh-pages -d dist部署到GitHub Pages后，JS、CSS等静态资源无法正常加载。排查发现index.html被放置在与仓库同名的子文件夹中，导致资源路径匹配失效。此前尝试过npx vite optimize、调整vite.config.js、将dist设为子模块、修改.gitignore、切换多种资源路径格式、配置npm部署脚本等方法，均未解决问题。

核心解决步骤 #

1. 配置Vite的base路径 #

在项目根目录的vite.config.js文件中（如果没有则新建），添加base配置项，值为你的GitHub仓库名称（注意末尾要加斜杠）：

import { defineConfig } from 'vite'
// 这里根据你使用的框架引入对应插件，比如Vue项目引入vue插件
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  base: '/yaay/' // 替换为你的GitHub仓库名称，格式为/仓库名/
})

2. 重新构建项目 #

执行Vite构建命令，生成带有正确路径前缀的dist文件：

npm run build

3. 重新部署到GitHub Pages #

再次执行gh-pages部署命令：

gh-pages -d dist

原理说明 #

GitHub Pages的项目站点默认部署在https://<用户名>.github.io/<仓库名>/的子路径下，Vite默认构建的资源路径是根目录绝对路径（以/开头），会直接去https://<用户名>.github.io/下查找资源，自然找不到。通过设置base为仓库名称，Vite会自动为所有静态资源路径添加/仓库名/前缀，让资源路径匹配GitHub Pages的子目录结构，从而正常加载。

内容的提问来源于stack exchange，提问作者0w0