Vuetify项目生产构建空白页问题及GitHub Pages部署咨询

一、构建后空白页的核心原因与解决思路 #

你提到npm run preview能正常显示，说明构建产物本身没问题，空白页的核心原因几乎都是资源路径配置错误——本地预览是通过Vite的服务器提供服务，路径是根路径，但直接打开dist/index.html用的是file://协议，或者部署到GitHub Pages这类子路径环境时，资源引用路径不匹配。

具体修复步骤： #

1. 调整Vite的base路径
   打开vite.config.mts，添加/修改base配置：

   import { defineConfig } from 'vite'
   import vuetify from 'vite-plugin-vuetify'
   
   export default defineConfig({
     // 本地直接打开dist/index.html时设为相对路径
     // 部署到GitHub Pages子仓库时，替换为你的仓库名，比如'/my-vuetify-project/'
     base: './', 
     plugins: [vuetify({ autoImport: true })],
     // 其他原有配置...
   })
   

2. 重新构建并验证
   执行npm run build后，再次打开dist/index.html，或者检查控制台（F12）是否还有404的资源请求——如果路径配置正确，资源会正常加载，页面就能显示。

二、部署到GitHub Pages的完整步骤 #

不管是手动部署还是用GitHub Actions自动化部署，核心都是先配置正确的base路径，再把dist目录的内容推送到gh-pages分支。

方式1：手动部署 #

1. 确保vite.config.mts的base设为你的仓库名，比如仓库地址是https://username.github.io/my-app/，则base: '/my-app/'
2. 执行npm run build生成最新的dist目录
3. 安装部署工具：npm install -D gh-pages
4. 在package.json中添加部署脚本：

   "scripts": {
     "dev": "vite",
     "build": "vue-tsc && vite build",
     "preview": "vite preview",
     "deploy": "gh-pages -d dist"
   }
   

5. 执行npm run deploy，工具会自动把dist目录的内容推送到仓库的gh-pages分支
6. 进入GitHub仓库的「Settings」→「Pages」，设置部署源为gh-pages分支的根目录，保存后等待1-5分钟即可访问。

方式2：GitHub Actions自动部署 #

1. 在仓库根目录创建.github/workflows/deploy.yml文件，粘贴以下内容：

   name: Deploy to GitHub Pages
   
   on:
     push:
       branches: [ main ] # 替换成你的主分支名（比如master）
     workflow_dispatch:
   
   jobs:
     build-and-deploy:
       runs-on: ubuntu-latest
       steps:
         - name: Checkout code
           uses: actions/checkout@v4
   
         - name: Setup Node.js
           uses: actions/setup-node@v4
           with:
             node-version: 20 # 匹配你的项目Node版本
             cache: 'npm'
   
         - name: Install dependencies
           run: npm install
   
         - name: Build project
           run: npm run build
   
         - name: Deploy to Pages
           uses: peaceiris/actions-gh-pages@v4
           with:
             github_token: ${{ secrets.GITHUB_TOKEN }}
             publish_dir: ./dist
             publish_branch: gh-pages
   

2. 同样要把vite.config.mts的base设为你的仓库名
3. 推送代码到主分支，GitHub会自动触发Action，完成构建和部署
4. 前往仓库「Settings」→「Pages」确认部署状态，正常情况下几分钟后就能访问。

额外排查点 #

• 如果你的项目使用了Vue Router，要确保路由的历史模式配置和Vite的base一致：

  import { createRouter, createWebHistory } from 'vue-router'
  import routes from './routes'
  
  const router = createRouter({
    history: createWebHistory(import.meta.env.BASE_URL),
    routes,
  })
  

• 检查dist目录下的资源文件名是否正确，Vite默认会给资源加哈希值，确保index.html里的引用路径和实际文件一致。

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