Vite Vue3项目部署GitHub Pages无内容显示问题求助

针对你遇到的部署后页面空白、无报错但开发正常的情况，按以下步骤排查：

1. 检查Vue Router路由模式 #

GitHub Pages是静态托管服务，不支持Vue Router的history模式（需要服务器配置 fallback 规则），如果用了history模式会导致路由无法正确加载，页面空白。

修改你的路由配置文件（通常是src/router/index.js），把createWebHistory改成createWebHashHistory：

import { createRouter, createWebHashHistory } from 'vue-router'

const router = createRouter({
  history: createWebHashHistory(), // 替换原有的createWebHistory
  routes: [
    // 你的路由列表
  ]
})

2. 验证dist文件是否完整上传到gh-pages分支 #

• 登录GitHub，进入你的ptwa仓库，切换到gh-pages分支
• 确认分支根目录下有index.html和assets文件夹，且文件结构和本地dist目录一致（不要出现嵌套的dist文件夹）
• 如果文件缺失，重新执行npm run deploy，确保命令执行过程无报错

3. 检查页面资源加载路径 #

打开部署后的页面，按F12打开开发者工具：

• 切换到Network标签，刷新页面，查看所有资源的请求状态，是否有404错误
• 切换到Elements标签，查看index.html里的css、js引用路径是否以/ptwa/开头（和你vite.config.js里的base配置一致）

4. 本地预览生产构建产物 #

执行以下命令，模拟生产环境预览：

npm run build
npm run preview

如果本地预览也空白，说明问题出在构建环节，而非部署：

• 检查main.js里的Vue实例挂载代码，确保mount('#app')对应的元素在index.html中存在（比如<div id="app"></div>）
• 检查代码中是否有依赖绝对路径的资源引用（比如硬编码的/assets/xxx，应该用相对路径或@别名）

5. 确认GitHub Pages设置 #

进入仓库的Settings -> Pages：

• 确认Source选项选择的是gh-pages分支，根目录（/root）
• 等待设置生效（可能需要几分钟），再刷新页面测试

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