众所周知，微信小程序的开发需要依赖微信官方提供的开发工具（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 范围我们无法获得，这里需要关闭此功能

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

至此，准备工作已完成，我们已经给项目配置了 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」中看到执行进度和结果：

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

jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - id: preview
        name: Compile
        uses: crazyurus/miniprogram-action@1.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_type，env 传递密钥内容。这个 Action 会对小程序进行编译，并生成预览二维码，二维码图片的 Base64 内容会通过 outputs.preview_qrcode 返回
3. 运行 peter-evans/commit-comment 这个 Action，用来给 Commit 增加评论。我们把上一步获取到的二维码图片 Base64 评论到这个 Commit 上，在 Commit 左边即可看到一个评论图标：

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

如果我们要实现有人创建了 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@1.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 类型, preview 或 upload	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	上传的版本描述

需要注意的是，如果你的小程序代码不在项目的根目录下，则需要配置 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@1.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@1.0.0
        with:
          action_type: upload
          version: ${{ github.ref_name }}
        env:
          PRIVATE_KEY: ${{ secrets.PRIVATE_KEY }}

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

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

给项目增加 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 文件，获取 AppID、compileType、miniprogramRoot 以及 es6、minified 等编译参数，转换后传递给 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 的代码自己实现一个