# 小程序 CI 构建

QQ 小程序开发者可以在小程序项目中轻松接入 CI,在 git 操作时触发构建操作(上传小程序版本,设置体验版)。

说明:

  1. 文档中提供三种 CI 接入方式:GitHub ActionsDrone CI、直接运行 docker 镜像
  2. 小程序官方 Docker 构建镜像:qqminiapp/build:latest

# 准备工作

# 获取 appToken

appToken:用于小程序构建过程中的身份验证。

  • 打开 qq小程序管理端
  • 登录
  • 进入设置页面
  • 进入开发设置页
  • 点击生成 appToken
  • 管理员扫码
  • 得到 appToken

# 方式一:使用GitHub Actions

使用 Docker 镜像 + GitHub Actions 实现 QQ 小程序持续集成方案, 适用于 GitHub 的 QQ 小程序项目仓库。

# 关于GitHub Actions

GitHub Actions 是 GitHub 官方提供的持续集成( CI )服务,于 2018年10月推出,详见 官方文档

# qq小程序CI构建实现

# 一、 新建项目

GitHub 中新建小程序项目或打开已有小程序项目,可以在下图中看到 Actions 选项。

action菜单

# 二、 编辑GitHub Actions的yaml文件

在小程序项目根目录下增加文件 .github/workflows/test.yml 文件

小程序 CI 构建 yml 小例子如下:

name: CI

#写法一:在push事件时触发构建
on: [push] 

#写法二:在master分支的push操作时触发构建
#on:
#  push:
#    branches:
#    - master

jobs:
  build-qq-ci: #job名称

    runs-on: ubuntu-latest #运行环境

    steps:
    
	#第一步:获取小程序源码
    - name: Checkout 
      uses: actions/checkout@master
      
	#第二步:上传小程序版本到管理端,并将此版本设置为体验版(设置体验版可选)
    - name: Build 
      uses: docker://qqminiapp/build:latest 
      env: 
        PLUGIN_VERSION: 1.0.0
        PLUGIN_DESC: CI自动构建上传
        PLUGIN_APPTOKEN: ${{ secrets.APPTOKEN }}
        PLUGIN_BUILDUSER: ${{ github.actor }} 
        PLUGIN_EXPERIENCE: true 
        #PLUGIN_PREVIEW: true
        #PLUGIN_FIRSTPAGE: pages/index/index
        #PLUGIN_USEPACKAGEJSON: true
        #PLUGIN_NPMBUILD: true
        #PLUGIN_SOURCECODEPATH: ./test

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

说明:

  • env:需要传入镜像文件的参数。其中 PLUGIN_VERSIONPLUGIN_DESCPLUGIN_APPTOKEN必填,PLUGIN_BUILDUSERPLUGIN_EXPERIENCE 选填。
  • PLUGIN_VERSION:小程序版本号。
  • PLUGIN_DESC:小程序版本描述。
  • PLUGIN_APPTOKEN:从小程序管理端获取到的 appToken。此处可直接填 appToken,或者可以使用 secrets 变量 secrets.APPTOKEN。secrets 变量设置方式见下图。
  • PLUGIN_BUILDUSER:小程序开发版的发布者(小程序管理端->开发管理->开发版本的发布者)。此处使用了 GitHub 提供的 环境变量 github.actor( 构建者 GitHub 账号名 )。
  • PLUGIN_EXPERIENCE:表示是否把当前版本设置为体验版。true:设置为体验版;false 或不加此参数:只上传开发版本,不会被设置为体验版。
  • PLUGIN_PREVIEW:是否上传预览版小程序。true:是,无需填写版本号和版本描述;false或不加此参数:上传开发版或体验版到小程序管理端
  • PLUGIN_FIRSTPAGE:填写后,扫小程序二维码会默认打开此页面。
  • PLUGIN_USEPACKAGEJSON:是否使用项目根目录下的 package.json 中的版本号 version 和版本描述 uploadDesc。为 true 时,CI 配置中的 versiondesc 不需要填写,直接读取 。package.json 中的版本号和版本描述;为 false 或不填,则需要填写 CI 配置中的 versiondesc
  • PLUGIN_NPMBUILD:是否进行 npm 构建。true: 需要构建 npm (npm install + 构建 npm);false 或不填:不需要进行 npm 构建
  • PLUGIN_SOURCECODEPATH:小程序源码相对目录,例如:如果小程序源码不在根目录,在 dist 目录下,如何指定源码目录。方法一:如果项目根目录下存在 project.config.json 文件,可 添加配置 miniprogramRoot: dist 小程序源码目录参数(相对路径)。方法二:ci 配置文件中增加 PLUGIN_SOURCECODEPATH: ./dist 参数指定源码目录,这种方式需要注意 dist 目录下得有 project.config.json 文件

设置secrets.APPTOKEN

# 三、 执行构建操作

编写好 yml 文件后,执行 git push 操作时,GitHub Actions 就会触发构建操作了。

如下图中,打开 actions 菜单,点击 workflow runs 里面的工作流程,可以看到 GitHub Actions 的详细执行过程。在 build 的执行记录里,可以看到手Q打开体验版url消息。复制 url 地址在 QQ 中点击就可以打开体验版小程序了。

构建完成后,就可以在小程序管理端查看提交的体验版小程序了。

图一

# 方式二:使用 Drone CI

Drone CI 是一个开源 CI 工具,其原生支持 Docker,结合小程序 CI 构建 Docker 镜像能很方便的实现小程序的持续集成。详见 Drone官方文档

关于 Drone 的构建环境选择:

  1. Drone 官方提供的云构建环境(https://cloud.drone.io/):项目要求是公开的,不支持私有项目
  2. 开发者自己搭建私有构建环境( Drone CI 服务器 ):需要自己搭建 Drone 服务

# 使用方式

  1. 在 GitHub 中新建代码仓库

  2. 打开 https://cloud.drone.io 或开发者自己部署的 Drone 网站( 部署方式详见 https://docs.drone.io/installation/runners/ ),使用 GitHub 账号登录

  3. 在登录后的界面中可以看到构建记录

    构建记录

  4. 在小程序项目根目录编写 .drone.yml 的 CI 配置文件

    小程序 CI 构建小例子如下:

       # yml小例子
       kind: pipeline
       name: default
       
       steps:
         - name: CI Auto Build
           image: qqminiapp/build:latest
           settings:
             version: 1.0.0
             desc: CI自动构建上传 
             appToken: xxx
             buildUser: ${DRONE_REPO_OWNER} 
             experience: true
             #preview: true
             #firstPage: pages/logs/logs
             #usePackageJson: true 
             #npmBuild: true
             #sourceCodePath: ./test
    
           when: # CI构建触发时机
             event: push 
             branch: master
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22

    说明:

    • image: 需要在stages中使用qq小程序构建镜像( qqminiapp/build:latest )
    • settings:需要传入镜像文件的参数。其中 appToken 必填;buildUser、experience、firstPage 选填;usePackageJson 选填,当其为 true 时,可不填写 version 和 desc,当其为 false 或不填,则 version 和desc 必填。
    • version:小程序版本号
    • desc:小程序版本描述
    • appToken:QQ 小程序管理端获取的 appToken
    • buildUser:小程序开发版的发布者(小程序管理端->开发管理->开发版本的发布者)。推荐填写 Drone提供的环境变量。DRONE_BRANCH:分支名,DRONE_REPO_OWNER:git账号名。buildUser 选填,不填默认为“CI”,不同的 buildUser,会在开发者管理端生成不同版本。可使用 Drone 提供的 环境变量
    • experience:表示是否把当前版本设置为体验版。true:设置为体验版,false 或不加此参数:只上传开发版本,不会被设置为体验版。
    • preview:是否上传预览版小程序。true:是,无需填写版本号和版本描述;false 或不加此参数:上传开发版或体验版到小程序管理端
    • firstPage:扫描小程序二维码,默认打开的页面。
    • usePackageJson:是否使用小程序项目根目录下的 package.json 中的版本号 version 和版本描述 uploadDesc 。为 true 时,ci 配置文件中的version 和 desc 不生效,直接读取 package.json 中的版本号和版本描述;为 false 或不填,则需要填写 CI 配置中的 version、desc
    • npmBuild:是否进行 npm 构建。true: 需要构建 npm (npm install + 构建 npm);false 或不填:不需要进行 npm 构建
    • sourceCodePath:小程序源码相对目录,例如:如果小程序源码不在根目录,在 dist 目录下,如何指定源码目录?方法一:如果项目根目录下存在 project.config.json 文件,可 添加配置 miniprogramRoot: dist 小程序源码目录参数(相对路径)。方法二:ci 配置文件中增加 sourceCodePath: ./dist 参数指定源码目录,这种方式需要注意 dist 目录下得有 project.config.json 文件。
  5. 进行 git push 操作,在 https://cloud.drone.io/ 中可查看构建过程以及小程序访问地址。打开 qq小程序管理端,登录后打开开发管理,在开发版本中可以看到 push 后触发的 CI 构建上传的小程序版本。

# 方式三:运行 docker 镜像

可直接运行 docker 镜像来实现小程序构建(会在小程序根目录生成小程序二维码 qrcode.png),需安装 docker 环境,然后在终端中执行以下命令:

# 拉取小程序 ci 构建镜像到本地
docker pull qqminiapp/build:latest

# 运行 docker 镜像,其中:
# -e 用来向 docker 镜像中传递参数
# -v "E:/miniapptest":"/tmp" 表示将本地的小程序目录 E:/miniapptest,映射到 docker 中的 /tmp 目录
# -w 表示 docker 镜像里执行脚本时所在目录是 /tmp
docker run -e PLUGIN_VERSION=1.0.0 -e PLUGIN_DESC=版本描述 -e PLUGIN_APPTOKEN=** -e PLUGIN_EXPERIENCE=true -e PLUGIN_PREVIEW=false -e PLUGIN_BUILDUSER=user -e PLUGIN_FIRSTPAGE=pages/logs/logs -e PLUGIN_USEPACKAGEJSON=false -e PLUGIN_NPMBUILD=false -e PLUGIN_SOURCECODEPATH=./src -v "E:/miniapptest":"/tmp" -w /tmp "qqminiapp/build:latest"

# 或以下格式
docker run \
    -e PLUGIN_VERSION=1.0.0 \
    -e PLUGIN_DESC=版本描述 \
    -e PLUGIN_APPTOKEN=** \
    -e PLUGIN_EXPERIENCE=true \
    -e PLUGIN_PREVIEW=false \
    -e PLUGIN_BUILDUSER=user \
    -e PLUGIN_FIRSTPAGE=pages/logs/logs \
    -e PLUGIN_USEPACKAGEJSON=false \
    -e PLUGIN_NPMBUILD=false \
    -e PLUGIN_SOURCECODEPATH=./src \
    -v "E:/miniapptest":"/tmp" \
    -w /tmp "qqminiapp/build:latest"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

参数说明:

  • PLUGIN_VERSION:小程序版本号。
  • PLUGIN_DESC:小程序版本描述。
  • PLUGIN_APPTOKEN:从小程序管理端获取到的 appToken。
  • PLUGIN_BUILDUSER:小程序开发版的发布者(小程序管理端->开发管理->开发版本的发布者)。
  • PLUGIN_EXPERIENCE:表示是否把当前版本设置为体验版。true:设置为体验版,false 或不加此参数:只上传开发版本,不会被设置为体验版。
  • PLUGIN_PREVIEW:是否上传预览版小程序。true:是,无需填写版本号和版本描述;false或不加此参数:上传开发版或体验版到小程序管理端
  • PLUGIN_FIRSTPAGE:填写后,扫小程序二维码会默认打开此页面。
  • PLUGIN_USEPACKAGEJSON:是否使用项目根目录下的 package.json 中的版本号 version 和版本描述 uploadDesc。为 true 时,CI 配置中的 versiondesc 不需要填写,直接读取 。package.json 中的版本号和版本描述;为 false 或不填,则需要填写 CI 配置中的 versiondesc
  • PLUGIN_NPMBUILD:是否进行 npm 构建。true: 需要构建 npm (npm install + 构建 npm);false 或不填:不需要进行 npm 构建
  • PLUGIN_SOURCECODEPATH:小程序源码相对目录,例如:如果小程序源码不在根目录,在 dist 目录下,如何指定源码目录。方法一:如果项目根目录下存在 project.config.json 文件,可 添加配置 miniprogramRoot: dist 小程序源码目录参数(相对路径)。方法二:ci 配置文件中增加 PLUGIN_SOURCECODEPATH: ./dist 参数指定源码目录,这种方式需要注意 dist 目录下得有 project.config.json 文件