使用GitHub Actions和GitHub pages实现前端项目的自动打包部署

上面说了，每个 action 就是一个独立脚本，因此可以做成代码仓库，使用userName/repoName的语法引用 action。比如，actions/setup-node就表示github.com/actions/setup-node这个仓库，它代表一个 action，作用是安装 Node.js。事实上，GitHub 官方的 actions 都放在 github.com/actions 里面。

既然 actions 是代码仓库，当然就有版本的概念，用户可以引用某个具体版本的 action。下面都是合法的 action 引用，用的就是 Git 的指针概念，详见官方文档。

actions/setup-node@74bc508 # 指向一个 commit
actions/setup-node@v1.0 # 指向一个标签
actions/setup-node@master# 指向一个分支

二、基本概念

GitHub Actions 有一些自己的术语。

（1）workflow （工作流程）：持续集成一次运行的过程，就是一个 workflow。

（2）job （任务）：一个 workflow 由一个或多个 jobs 构成，含义是一次持续集成的运行，可以完成多个任务。

（3）step（步骤）：每个 job 由多个 step 构成，一步步完成。

（4）action （动作）：每个 step 可以依次执行一个或多个命令（action）。

三、workflow 文件

GitHub Actions 的配置文件叫做 workflow 文件，存放在代码仓库的.github/workflows目录。

workflow 文件采用 YAML 格式，文件名可以任意取，但是后缀名统一为.yml，比如foo.yml。一个库可以有多个 workflow 文件。GitHub 只要发现.github/workflows目录里面有.yml文件，就会自动运行该文件。

workflow 文件的配置字段非常多，详见官方文档。下面是一些基本字段。

（1）`name`

name字段是 workflow 的名称。如果省略该字段，默认为当前 workflow 的文件名。

复制代码

name: GitHub Actions Demo

（2）`on`

on字段指定触发 workflow 的条件，通常是某些事件。

复制代码

on: push

上面代码指定，push事件触发 workflow。

on字段也可以是事件的数组。

复制代码

on: [push, pull_request]

上面代码指定，push事件或pull_request事件都可以触发 workflow。

完整的事件列表，请查看官方文档。除了代码库事件，GitHub Actions 也支持外部事件触发，或者定时运行。

（3）`on.<push|pull_request>.<tags|branches>`

指定触发事件时，可以限定分支或标签。

复制代码

on:
  push:
    branches:    
      - master

上面代码指定，只有master分支发生push事件时，才会触发 workflow。

（4）`jobs.<job_id>.name`

复制代码

jobs:
  my_first_job:
    name: My first job
  my_second_job:
    name: My second job

面代码的jobs字段包含两项任务，job_id分别是my_first_job和my_second_job。

（5）`jobs.<job_id>.needs`

needs字段指定当前任务的依赖关系，即运行顺序。

复制代码

jobs:
  job1:
  job2:
    needs: job1
  job3:
    needs: [job1, job2]

上面代码中，job1必须先于job2完成，而job3等待job1和job2的完成才能运行。因此，这个 workflow 的运行顺序依次为：job1、job2、job3。

（6）`jobs.<job_id>.runs-on`

runs-on字段指定运行所需要的虚拟机环境。它是必填字段。目前可用的虚拟机如下。

复制代码

ubuntu-latest，ubuntu-18.04或ubuntu-16.04
windows-latest，windows-2019或windows-2016
macOS-latest或macOS-10.14

下面代码指定虚拟机环境为ubuntu-18.04。

复制代码

runs-on: ubuntu-18.04

（7）`jobs.<job_id>.steps`

steps字段指定每个 Job 的运行步骤，可以包含一个或多个步骤。每个步骤都可以指定以下三个字段。

复制代码

jobs.<job_id>.steps.name：步骤名称。
jobs.<job_id>.steps.run：该步骤运行的命令或者 action。
jobs.<job_id>.steps.env：该步骤所需的环境变量。

下面是一个完整的 workflow 文件的范例。

复制代码

name: Greeting from Mona
on: push

jobs:
  my-job:
    name: My Job
    runs-on: ubuntu-latest
    steps:
    - name: Print a greeting
      env:
        MY_VAR: Hi there! My name is
        FIRST_NAME: Mona
        MIDDLE_NAME: The
        LAST_NAME: Octocat
      run: |
        echo $MY_VAR $FIRST_NAME $MIDDLE_NAME $LAST_NAME.

上面代码中，steps字段只包括一个步骤。该步骤先注入四个环境变量，然后执行一条 Bash 命令。

四、实例：vue项目发布到 GitHub Pages

用GitHub Actions和GitHub Pages就能实现前端项目的自动部署，每次提交代码都会自动构建并更新网站

这里笔者简要记录使用GitHub Actions和GitHub Pages实现Vue项目的自动构建与发布，详细的使用文档请参考官方文档

项目准备

创建一个Vue3项目

复制代码

npm create vue@latest

这一指令将会安装并执行 create-vue，它是 Vue 官方的项目脚手架工具。你将会看到一些诸如 TypeScript 和测试支持之类的可选功能提示：

复制代码

✔ Project name: ... <your-project-name>
✔ Add TypeScript? ... No / Yes
✔ Add JSX Support? ... No / Yes
✔ Add Vue Router for Single Page Application development? ... No / Yes
✔ Add Pinia for state management? ... No / Yes
✔ Add Vitest for Unit testing? ... No / Yes
✔ Add an End-to-End Testing Solution? ... No / Cypress / Nightwatch / Playwright
✔ Add ESLint for code quality? ... No / Yes
✔ Add Prettier for code formatting? ... No / Yes
✔ Add Vue DevTools 7 extension for debugging? (experimental) ... No / Yes

Scaffolding project in ./<your-project-name>...
Done.

如果不确定是否要开启某个功能，你可以直接按下回车键选择 No。在项目被创建后，通过以下步骤安装依赖并启动开发服务器：

复制代码

$ cd <your-project-name>
$ npm install
$ npm run dev

创建打包部署脚本

首先在项目里创建.github文件夹，然后创建workflows文件夹

在workflows文件夹下创建一个.yml文件，笔者这样叫deploy.yml，任意名字都行

在刚才创建的.yml编写打包部署的代码

复制代码

name: Build and Deploy # workflow 的名称
on: [push] # 触发条件
permissions:
  contents: write
jobs: # 任务的集合
  build-and-deploy: # 任务的名称
    runs-on: ubuntu-latest # 运行环境
    steps: # 任务的步骤
      - name: Checkout 🛎️ # 步骤的名称
        uses: actions/checkout@v6 # 步骤的使用的 action

      - name: Install and Build 🔧 # 运行的命令
        run: |
          npm install -g pnpm
          pnpm install
          pnpm run docs:build

      - name: Deploy 🚀
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          folder: docs/.vitepress/dist # The folder the action should deploy.

上面的脚本参考自：Deploy to GitHub Pages · Actions · GitHub Marketplace

整个流程在master分支发生push事件时触发。

只有一个job，运行在虚拟机环境ubuntu-latest。

第一步是获取源码，使用的 action 是actions/checkout。

第二步是构建和部署，使用的 action 是JamesIves/github-pages-deploy-action。

第二步需要四个环境变量，分别为 GitHub 密钥、发布分支、构建成果所在目录、构建脚本。其中，只有 GitHub 密钥是秘密变量，需要写在双括号里面，其他三个都可以直接写在文件里。

这些配置也很容易理解，这里有一点要说明，GitHub Actions支持直接复用别人写的脚本，上面的actions/checkout@v4和JamesIves/github-pages-deploy-action@v4就是官方和别人仓库使用的GitHub Actions脚本

通常情况下，找个合适的GitHub Actions脚本就能满足使用

现在去GitHub创建一个空项目

根据空项目的提示，现在在Vue项目里面执行Git初始化和关联远程仓库并推送项目

复制代码

git init
git add .
git commit -m "first commit"
git branch -M master
git remote add origin <远程Git仓库地址>
git push -u origin master

现在，GitHub仓库里应该就有了代码

Github Actions会自动执行deploy.yml里的文件，进行打包和部署（自动创建gh-pages分支）

此时，离发布到网站还需要开启GitHub Pages，开启步骤如下图所示

在Settings里的Pages下配置从gh-pages分支部署网站

此时提交代码，就会自动推送到网站https://<GitHub账户名>.github.io/actions_pages_test/

此时还需要配置一点东西，就是Vite的打包路径，不然资源会访问不到

把这次修改推送到GitHub仓库，就会自动触发打包部署

点击右侧的github-pages就能看到部署的网站

点击网址即可访问

后续的修改，只要push到GitHub，都会自动打包部署

使用GitHub Actions和GitHub pages实现前端项目的自动打包部署

一、GitHub Actions 是什么？

二、基本概念

三、workflow 文件

（1）name

（2）on

（3）on.<push|pull_request>.<tags|branches>

（4）jobs.<job_id>.name

（5）jobs.<job_id>.needs

（6）jobs.<job_id>.runs-on

（7）jobs.<job_id>.steps

四、实例：vue项目发布到 GitHub Pages

项目准备

创建打包部署脚本

（1）`name`

（2）`on`

（3）`on.<push|pull_request>.<tags|branches>`

（4）`jobs.<job_id>.name`

（5）`jobs.<job_id>.needs`

（6）`jobs.<job_id>.runs-on`

（7）`jobs.<job_id>.steps`