Vite + Vue 项目部署到 GitHub Pages（保姆级教程）

最近写了一个基于 Vite + Vue 的小 Demo，想着部署到 GitHub Pages，既可以在线访问，也方便展示项目。整个过程其实并不复杂，不过第一次部署的时候还是踩了一些坑，所以记录一下完整流程，希望能帮到有需要的人。

一、将项目上传到 GitHub

首先，把本地项目推送到 GitHub 仓库。

假设仓库名称为：

复制代码

vite-demo

后面的配置都会用到这个仓库名。

二、安装部署工具

在项目根目录执行：

复制代码

npm install gh-pages --save-dev

如果使用的是 pnpm：

复制代码

pnpm add -D gh-pages

安装完成后，就可以利用 gh-pages 将打包后的静态文件上传到 GitHub Pages。

三、修改 Vite 配置

这是最容易忽略的一步。

打开 vite.config.js（或 vite.config.ts），修改 base 配置：

复制代码

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  base: '/vite-demo/',
})

其中：

复制代码

base: '/vite-demo/'

这里的 vite-demo 必须和你的 GitHub 仓库名称保持一致。

例如仓库名称是：

复制代码

my-project

那么应该写成：

复制代码

base: '/my-project/'

如果没有配置 base，部署完成后通常会出现页面空白、CSS 和 JavaScript 加载失败等问题。

四、修改 package.json

在 scripts 中新增一个部署命令：

复制代码

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "deploy": "gh-pages -d dist"
  }
}

这样以后只需要执行一条命令即可完成部署。

五、打包项目

执行：

复制代码

npm run build

打包完成后，项目根目录会生成一个 dist 文件夹，这里面就是最终需要部署的静态资源。

六、部署到 GitHub Pages

执行：

复制代码

npm run deploy

执行成功后，gh-pages 会自动创建（或更新）一个 gh-pages 分支，并将 dist 中的内容上传到该分支。

七、开启 GitHub Pages

进入 GitHub 仓库：

复制代码

Settings

找到：

复制代码

Pages

然后进行如下配置：

复制代码

Build and deployment

Source：
Deploy from a branch

Branch：
gh-pages

Folder：
/(root)

保存即可。

稍等几十秒到一两分钟，GitHub 就会完成部署。

访问地址通常为：

复制代码

https://你的用户名.github.io/vite-demo/

八、Vue Router 的注意事项

如果项目使用了 Vue Router，并且采用的是：

复制代码

createWebHistory()

那么直接刷新页面时，大概率会出现 404。

原因是 GitHub Pages 只能托管静态资源，不支持服务端路由。

最简单的解决方法就是改成：

复制代码

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

const router = createRouter({
  history: createWebHashHistory(),
  routes,
})

export default router

部署后的地址会变成：

复制代码

https://用户名.github.io/vite-demo/#/

虽然 URL 中会多一个 #，但刷新页面不会再出现 404。

九、更推荐的部署方式：GitHub Actions

如果只是偶尔部署一次，使用 gh-pages 已经足够。

但如果项目需要经常更新，建议直接使用 GitHub Actions。

配置完成之后，只要执行：

复制代码

git push

GitHub 就会自动完成：

安装依赖
构建项目
发布到 GitHub Pages

整个过程完全自动化，不需要每次都执行 npm run deploy。

对于长期维护的项目，这种方式更加方便，也更符合现在主流的部署流程。

感兴趣可看我下一篇文章

总结

整个部署流程可以简单概括为下面几个步骤：

将项目上传到 GitHub。
安装 gh-pages。
配置 vite.config 中的 base。
在 package.json 中添加部署命令。
执行 npm run build。
执行 npm run deploy。
在 GitHub Pages 中选择 gh-pages 分支进行发布。

第一次部署时，最容易踩坑的地方就是 base 配置 和 Vue Router 刷新 404。只要这两个地方处理好，基本都能顺利完成部署。

希望这篇文章能帮到正在学习 Vite 和 Vue 的同学，如果还有其他部署问题，也欢迎一起交流。