Vite + Vue 项目使用 GitHub Actions 自动部署到 GitHub Pages（2026 最新版）

平时写一些 Vue Demo 或个人项目为了方便展示一般都会部署到 GitHub Pages。以前我一直使用gh-pages手动部署每次更新代码都要执行npm run build npm run deploy虽然不算麻烦但时间长了还是觉得效率不高。后来换成了GitHub Actions 自动部署现在只要执行一次git pushGitHub 就会自动完成项目构建、部署全程无需手动操作。本文记录一下完整的配置流程以及我在配置过程中遇到的几个坑。最终效果整个流程如下修改代码 │ ▼ git push │ ▼ GitHub Actions 自动运行 │ ▼ 安装依赖 │ ▼ Vite 打包 │ ▼ 部署到 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: /taobao/, })这里需要注意base: /taobao/其中taobao必须改成自己的GitHub 仓库名称。例如仓库叫my-demo那么应该写成base: /my-demo/否则部署之后页面可能会出现空白或者 CSS、JavaScript 加载失败。二、创建 GitHub Actions 工作流在项目根目录创建.github └── workflows └── deploy.yml目录结构如下project │ ├── src ├── public ├── package.json ├── vite.config.js └── .github └── workflows └── deploy.yml三、编写 deploy.yml复制下面的配置即可。注意目前 GitHub 已经逐步淘汰 Node.js 20建议直接使用 Node.js 22。name: Deploy Vite to GitHub Pages on: push: branches: - main permissions: contents: read pages: write id-token: write concurrency: group: pages cancel-in-progress: true jobs: build: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkoutv4 - name: Setup Node uses: actions/setup-nodev4 with: node-version: 22 cache: npm - name: Install Dependencies run: npm install - name: Build Project run: npm run build - name: Upload Pages Artifact uses: actions/upload-pages-artifactv3 with: path: ./dist deploy: needs: build runs-on: ubuntu-latest environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} permissions: pages: write id-token: write steps: - name: Deploy id: deployment uses: actions/deploy-pagesv4如果你使用的是pnpm把run: npm install修改为run: pnpm install同时run: npm run build修改成run: pnpm build即可。四、开启 GitHub Pages进入仓库Settings ↓ Pages找到Build and deployment将Source修改为GitHub Actions不要选择Deploy from a branch配置完成后保存即可。如果看到类似下面的信息Your site is live at https://用户名.github.io/仓库名/说明 Pages 已经配置成功。五、提交代码如果本地和远程都是main分支git add . git commit -m 配置 GitHub Actions 自动部署 git push origin main如果像我一样本地分支masterGitHub 分支mainGitHub 远程仓库名称github则执行git add . git commit -m 配置 GitHub Actions 自动部署 git push github master:main这里的master:main表示将本地master分支推送到 GitHub 的main分支。GitHub Actions 监听的是GitHub 仓库中的main分支因此这种推送方式同样可以正常触发自动部署。六、查看是否部署成功代码推送完成后进入仓库顶部Actions如果配置正确会看到类似下面的工作流Deploy Vite to GitHub Pages正常情况下会经历Queued ↓ In progress ↓ Success最后所有步骤都会显示绿色。例如✔ Checkout ✔ Setup Node ✔ Install Dependencies ✔ Build Project ✔ Upload Pages Artifact ✔ Deploy说明自动部署已经成功。七、如何验证网站已经更新建议第一次配置完成后可以故意修改一个比较明显的地方例如首页标题h1GitHub Actions 自动部署成功/h1提交代码git add . git commit -m 测试自动部署 git push github master:main等待几十秒后刷新网页。如果页面内容已经更新说明整套自动部署流程已经生效。以后每次提交代码网站都会自动更新。八、我遇到的几个坑1、base 配置错误最常见的问题。base: /仓库名/这里一定要和 GitHub 仓库名称保持一致。否则页面容易白屏。2、Pages Source 选择错误第一次配置时我选择的是Deploy from a branch导致 GitHub Actions 无法正常部署。后来修改为GitHub Actions问题就解决了。3、本地和远程分支名称不同我的项目比较特殊Gitee 远程仓库叫originGitHub 远程仓库叫github本地分支是masterGitHub 默认分支是main因此推送命令为git push github master:main开始还担心 GitHub Actions 不会触发。后来发现GitHub Actions 只关心GitHub 仓库最终更新的是哪个分支并不关心你本地分支叫什么。只要最终更新的是main工作流就会自动执行。总结相比gh-pages手动部署GitHub Actions 最大的优势就是自动化。整个配置只需要完成一次后续每次推送代码都会自动拉取最新代码安装依赖构建项目部署到 GitHub Pages整个过程完全不用人工干预。对于 Vue、React、Vite 等静态项目来说这也是目前比较推荐的一种部署方式。如果你正在做个人博客、作品集或者 Demo 展示不妨尝试一下 GitHub Actions相信会比手动部署省心不少。