Github Actions + Github Pages 自动发布 Vue3 + Vite 项目

目的：提交代码，自动触发构建，并发布到 Github Pages 上

不详细讲为什么，只讲在怎么做

项目准备

1. 先在github上准备一个前端项目，我使用vue3搭建了一个前端项目，技术栈为：vue3、vite、element-plus、pinia、vue-router、headlessui、tailwindcss、typescript

如何搭建可看这篇：《vue3 + vite + element-plus + tailwindcss + typescript 实战项目》

2. 前端项目情况：只有main分支；项目文件如下图，代码在这

Github Pages 配置

可以理解为免费的线上服务器，可展示 build 后的前端项目

1. 开启配置

2. 开启配置后，再刷新下页面（没有的话可强刷、关闭重进），可以看到访问地址

3. 访问下地址，发现页面是空白的，打开控制台，发现有 html 结构，原因是：会默认加载了该 github 项目下根目录的 index.html 文件

4. 现在去改一下该 github 项目根目录的 index.html 文件，加个点文字，然后提交代码

等个 1、2 分钟，再刷新访问网址，就能看到最新的内容

5. 至此简单的 github pages 配置完成，可以放只有一个 .html 的在线简历

Github Actions 配置

可以理解为 CI、CD

入门文档可看这篇：GitHub Actions 入门教程 - 阮一峰的网络日志

可以配合上面的 Github Pages，实现提交代码，自动构建并发布的效果。

1. 更改Github Pages配置，改为Github Actions形式

2. 创建Github Actions的配置

3. 会帮我们生成了一个最基本的配置，然后我们提交到mian分支上

4. 提交后，我们进入Actions下，可看到第一个workflows

5. 现在去改一下该 github 项目根目录的 index.html 文件，再加点文字，然后提交代码

6. 然后去Actions下，看又有了一个workflow

7. 然后等它成功后，访问下该项目的 Github Pages，看到内容也变化了

8. 至此简单的 github actions 配置完成，结合 github pages 可以放只有一个 .html 的在线简历，实现提交代码自动部署功能（虽然没啥用）

Vue3 + Vite 项目接入

上面的流程比较简单，真正的项目是需要：提交代码后，触发构建、生成 dist、部署 dist，最终实现页面内容的更新

本次项目的线上代码地址：在这

1. 将项目拉取到本地：git clone xxx
2. 先在本地跑下构建命令，确定没得问题
3. 更改vite.config.ts配置，将打包目录改为 github 项目目录

4. 更改.github/workflows/static.yml配置，加入打包流程：

5. 完整代码如下（pnpm 版）：

# Simple workflow for deploying static content to GitHub Pages
name: Deploy static content to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ['main']

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: 'pages'
  cancel-in-progress: false

jobs:
  # Single deploy job since we're just deploying
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - uses: pnpm/action-setup@v2
        with:
          version: 8
      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: 20
          cache: 'pnpm'
      - name: Install dependencies
        run: pnpm install
      - name: Build
        run: pnpm run build
      - name: Setup Pages
        uses: actions/configure-pages@v4
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          # Upload entire repository
          path: './dist'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

6. 完整代码如下（npm 版）：

# Simple workflow for deploying static content to GitHub Pages
name: Deploy static content to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ['main']

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: 'pages'
  cancel-in-progress: false

jobs:
  # Single deploy job since we're just deploying
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: 20
          cache: 'npm'
      - name: Install dependencies
        run: npm install
      - name: Build
        run: npm run build
      - name: Setup Pages
        uses: actions/configure-pages@v4
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          # Upload entire repository
          path: './dist'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

7. 提交一下代码，然后去看Actions状态

8. 如果觉得频繁跳到 github 麻烦，可以安装 VScode 插件：GitHub Actions，然后在 VScode 里面直接看，并且还可点击直接打开网页的github actions内

9. actions 成功后，打开项目的 github pages 访问地址，看看是否对了，已经对了

10. 然后点点页面，跳转下路由，都是对的
11. 但是刷新下发现就 404 了，这不是浪费感情吗？

别急，这个原因是前端项目采用了history的路由模式，对github pages来说，访问https://mrhzq.github.io/vue3-vite-element-plus-tailwindcss-typescript/about是访问/about目录下的index.html

但我们哪有/about目录，所以就去找访问目录(我们配的/dist)下的404.html，没找到就显示官方的 404 页面

问题处理

Github Pages 刷新后，页面 404

原因上面一行就有写，不赘述；正确的处理方式是：配置 nginx，将其他路径的访问全部都指向 index.html。但 Github Pages 我们没法这样去处理，所以只能"取巧"

1、前端项目采用hash模式，重新触发actions后，就完全正常了，但地址就不好看，看个人选择 。只需改路由就行，然后提交代码，等actions成功，就可以任意刷新

2、在访问目录(我们配的/dist)下的创建一个404.html，内容跟index.html一模一样，这样显示404.html时也跟正常显示index.html一样

我们可以在打包成功了，复制下index.html，命名为404.html就行

a、package.json新增一个404build命令，用于生成404.html

{
  // ...
  "scripts": {
    // ...
      
    "404build": "cp dist/index.html dist/404.html"
  },
}

b、.github/workflows/static.yml新增一个404Build步骤

- name: 404Build
run: npm run 404build

c、提交代码，等actions成功，就可以任意刷新

Github Actions 失败处理

失败的，github 会发邮件给你哦

1. 找到失败的

2. 进入详情

报错：Supported file patterns: package-lock.json,npm-shrinkwrap.json,yarn.lock

因为我使用的是 pnpm，所以项目中没有 package-lock.json 文件。

处理方式：npm i，生成一个package-lock.json然后提交代码