Cr4zy Uru5 blogs
利用 GitHub Actions 实现小程序的持续集成

众所周知,微信小程序的开发需要依赖微信官方提供的开发工具(IDE),在 IDE 中完成小程序的真机预览和上传,每次都要手动操作还是比较麻烦的。对于托管在 GitHub 的项目,我们可以利用 GitHub 提供的 GitHub Actions 这一能力,实现小程序的持续集成(CI/CD)。

我们主要利用了 GitHub Action for WeChat MiniProgram 这个 Action,实现了以下自动化流程:

  1. 当 Commit 推送到 master 分支时,触发小程序预览并显示预览二维码
  2. 当有人创建了 Pull Request 时,触发小程序预览并显示预览二维码
  3. 当创建版本 Tag 并推送到 GitHub 时,触发小程序的构建和上传

更多有关小程序 GitHub Actions 的玩法,也欢迎探索和交流~

准备工作

在使用 GitHub Action for WeChat MiniProgram 前,需要先准备好小程序代码上传密钥,这是用于小程序开发者身份鉴权的凭证。获取步骤如下:

  1. 登录微信小程序管理后台 https://mp.weixin.qq.com
  2. 登录后在左侧菜单依次找到「开发」—「开发管理」,在右侧界面找到「开发设置」Tab。向下滚动找到「小程序代码上传」模块,点击「生成」按钮。管理员使用微信扫码后,获得密钥文件并下载
  3. 关闭「IP 白名单」功能。因为执行 GitHub Actions 的机器 IP 范围我们无法获得,这里需要关闭此功能

image.png

  1. 打开 GitHub 小程序项目的「Settings」,在左侧菜单依次找到「Secrets」—「Actions」,点击右上角按钮「New repository secret」,「Name」输入 PRIVATE_KEY,「Secret」粘贴第 2 步中密钥文件的内容,点击「Add secret」保存

image.png

至此,准备工作已完成,我们已经给项目配置了 GitHub Actions 所需的密钥。

在项目中使用

示例项目:crazyurus/recruit-miniprogram

首先在项目根目录下创建 .github/workflows 文件夹,再根据我们的需求编写 YAML 文件

实现小程序预览

workflows 目录下新建 preview.yaml。我们需要当 Commit 推送到 master 分支时触发小程序预览。因此在 preview.yaml 中添加:

name: 提交 Commit 预览小程序
on:
  push:
    branches:
      - master

命中该条件时,这个 YAML 就会被 GitHub Actions 执行,我们可以在项目的「Actions」中看到执行进度和结果:

image.png

接下来需要给 preview.yaml 定义具体的行为,在其中添加:

jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - id: preview
        name: Compile
        uses: crazyurus/miniprogram-action@2.0.0
        with:
          action_type: preview
        env:
          PRIVATE_KEY: ${{ secrets.PRIVATE_KEY }}
      - name: QR Code
        uses: peter-evans/commit-comment@v2
        with:
          body: |
            Copy the following content to the address bar of the browser to open the preview QR code

            ```
            ${{ steps.preview.outputs.preview_qrcode }}
            ```

其中,jobs.preview 是 Job 的名称,runs-on 是 Job 运行环境,steps 是运行步骤。这个 Job 主要有 3 步:

  1. Checkout 项目代码
  2. 运行 crazyurus/miniprogram-action 这个 Action(即前面提到的 GitHub Action for WeChat MiniProgram),id 是 Step 的唯一标识(用于后面取 outputs),with 传递参数 action_typeenv 传递密钥内容。这个 Action 会对小程序进行编译,并生成预览二维码,二维码图片的 Base64 内容会通过 outputs.preview_qrcode 返回
  3. 运行 peter-evans/commit-comment 这个 Action,用来给 Commit 增加评论。我们把上一步获取到的二维码图片 Base64 评论到这个 Commit 上,在 Commit 左边即可看到一个评论图标:

image.png

点击后即可看到这条评论和二维码内容。由于 GitHub Markdown 的限制,我们暂时无法使用图片格式语法展示 Base64 图片,需要将内容复制后粘贴到浏览器地址栏即可预览。

image.png

如果我们要实现有人创建了 Pull Request 时,触发小程序预览并显示预览二维码。只需要:

  • 新建 pull-request.yaml
  • 更换 on 中的触发条件,改为 pull_request
  • 修改第 3 步中的 Action,替换为 dannyskoog/pull-request-comment,用来给 Pull Request 增加评论

完整配置如下:

name: 创建 Pull Request 预览小程序
on:
  pull_request:
    branches: master
    types: [opened, synchronize, reopened]
jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - id: preview
        name: Compile
        uses: crazyurus/miniprogram-action@2.0.0
        with:
          action_type: preview
        env:
          PRIVATE_KEY: ${{ secrets.PRIVATE_KEY }}
      - name: QR Code
        uses: dannyskoog/pull-request-comment@v1
        with:
          message: |
            Copy the following content to the address bar of the browser to open the preview QR code

            ```
            ${{ steps.preview.outputs.preview_qrcode }}
            ```

如果需要预览时指定场景值、页面路径、页面参数等,GitHub Action for WeChat MiniProgram 也同样支持,在 with 增加参数即可。支持的参数如下:

参数 是否必填 描述 默认值
action_type false Action 类型, previewupload upload
project_path false 项目路径,需包含 project.config.json 文件 .
page_path false 预览的页面路径,例如 pages/index/index app.json 中第一个页面
page_query false 预览的页面参数,例如 a=b&c=1
scene false 场景值,详细见 微信官方文档 1011
version false 上传的版本号 1.0.0
description false 上传的版本描述
ci false CI 编号,1-30 24

需要注意的是,如果你的小程序代码不在项目的根目录下,则需要配置 project_path 参数指定小程序的目录(project.config.json 文件所在的目录)。例如使用了 Taro 等框架,需要由框架编译后再运行,则需要指定 project_path 为编译后的目录 dist,并且在 YAML 文件中的 Compile Job 前需要增加框架依赖安装和编译的步骤。YAML 如下:

jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Install dependencies
        run: npm ci
      - name: Taro compile
        run: npm run build:weapp
      - name: Compile
        uses: crazyurus/miniprogram-action@2.0.0
        with:
          action_type: preview
          project_path: dist
        env:
          PRIVATE_KEY: ${{ secrets.PRIVATE_KEY }}

实现小程序上传

我们使用 Git Tag 触发小程序的发布,例如执行以下命令:

$ git tag 2.3.4
$ git push --tags

此时会在最新的 Commit 创建一个 2.3.4 的 Tag。我们基于这个 Commit 发布小程序的 2.3.4 版本,因此需要 GitHub Actions 触发小程序上传。

workflows 目录下新建 upload.yaml,并添加:

name: 上传小程序
on:
  push:
    tags:
      - "*.*.*"
jobs:
  upload:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Upload
        uses: crazyurus/miniprogram-action@2.0.0
        with:
          action_type: upload
          version: ${{ github.ref_name }}
        env:
          PRIVATE_KEY: ${{ secrets.PRIVATE_KEY }}

其中,github.ref_name 这里代表标签名称,我们将标签名称作为版本号传递给 Action,再由 Action 上传到微信服务端。上传后效果如下:

image.png

接下来在微信小程序管理后台提交审核即可。

给项目增加 Badge

至此小程序项目就成功接入了 GitHub Actions,我们还可以给项目 README.md 增加徽章(Badge),用于显示项目的持续集成状态。将以下图片添加到 README.md 中:

![预览](https://github.com/crazyurus/recruit-miniprogram/actions/workflows/preview.yaml/badge.svg)

其中,crazyurus/recruit-miniprogram 需要替换为你的项目名称,preview.yaml 需要替换为你的 YAML 文件名。

效果如下:

预览

更多方式可参见 GitHub 官方文档 Adding a workflow status badge

实现原理

Action 实现:crazyurus/miniprogram-action

GitHub Action for WeChat MiniProgram 基于微信官方提供的 miniprogram-ci 实现了小程序的预览和上传。主要逻辑如下:

  • 输入参数读取,使用 @actions/core 提供的 getInput 方法
  • 使用环境变量 process.env.PRIVATE_KEY 获取密钥,process.env.GITHUB_WORKSPACE 获取小程序项目路径
  • 读取小程序 project.config.json 文件,获取 AppIDcompileTypeminiprogramRoot 以及 es6minified 等编译参数,转换后传递给 miniprogram-ci
  • 若小程序项目存在 package.json,则在预览或上传前调用 ci.packNpm 对小程序中的 NPM 依赖进行构建
  • 根据参数 action_type 决定调用 ci.preview 还是 ci.upload
  • 小程序预览执行完成,通过 @actions/core 提供的 setOutput 方法将二维码输出

总结

我们使用 GitHub Action for WeChat MiniProgram 实现了小程序项目的持续集成,在 Commit 或 Pull Request 时触发预览并生成二维码,在添加 Tag 时上传小程序到管理后台。

总而言之,GitHub Actions 的功能十分强大,接下来你还可以探索:

  • 给项目增加更多的自动化流程,例如 Pull Request 被合并后也触发上传。推荐阅读阮一峰的 GitHub Actions 入门教程 了解更多用法
  • 给项目引入更多的 GitHub Actions 让流程更强大,例如将生成的二维码通过飞书机器人发送给自己或群、基于 miniprogram-automator 实现小程序的自动化测试等。更多的 GitHub Actions 可以到 GitHub Actions 市场 获取
  • 当现有的 GitHub Actions 无法满足项目的需求时,可以参考 GitHub Actions 开发文档 和 GitHub Action for WeChat MiniProgram 的代码自己实现一个