众所周知,微信小程序的开发需要依赖微信官方提供的开发工具(IDE),在 IDE 中完成小程序的真机预览和上传,每次都要手动操作还是比较麻烦的。对于托管在 GitHub 的项目,我们可以利用 GitHub 提供的 GitHub Actions 这一能力,实现小程序的持续集成(CI/CD)。
我们主要利用了 GitHub Action for WeChat MiniProgram 这个 Action,实现了以下自动化流程:
- 当 Commit 推送到
master
分支时,触发小程序预览并显示预览二维码 - 当有人创建了 Pull Request 时,触发小程序预览并显示预览二维码
- 当创建版本 Tag 并推送到 GitHub 时,触发小程序的构建和上传
更多有关小程序 GitHub Actions 的玩法,也欢迎探索和交流~
准备工作
在使用 GitHub Action for WeChat MiniProgram 前,需要先准备好小程序代码上传密钥,这是用于小程序开发者身份鉴权的凭证。获取步骤如下:
- 登录微信小程序管理后台 https://mp.weixin.qq.com
- 登录后在左侧菜单依次找到「开发」—「开发管理」,在右侧界面找到「开发设置」Tab。向下滚动找到「小程序代码上传」模块,点击「生成」按钮。管理员使用微信扫码后,获得密钥文件并下载
- 关闭「IP 白名单」功能。因为执行 GitHub Actions 的机器 IP 范围我们无法获得,这里需要关闭此功能
- 打开 GitHub 小程序项目的「Settings」,在左侧菜单依次找到「Secrets」—「Actions」,点击右上角按钮「New repository secret」,「Name」输入
PRIVATE_KEY
,「Secret」粘贴第 2 步中密钥文件的内容,点击「Add secret」保存
至此,准备工作已完成,我们已经给项目配置了 GitHub Actions 所需的密钥。
在项目中使用
首先在项目根目录下创建 .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@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 步:
- Checkout 项目代码
- 运行
crazyurus/miniprogram-action
这个 Action(即前面提到的 GitHub Action for WeChat MiniProgram),id
是 Step 的唯一标识(用于后面取outputs
),with
传递参数action_type
,env
传递密钥内容。这个 Action 会对小程序进行编译,并生成预览二维码,二维码图片的 Base64 内容会通过outputs.preview_qrcode
返回 - 运行
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@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 类型, 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 |
上传的版本描述 | |
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 上传到微信服务端。上传后效果如下:
接下来在微信小程序管理后台提交审核即可。
给项目增加 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 的代码自己实现一个