小程序 CI 構建

QQ 小程序開發(fā)者可以在小程序項目中輕松接入 CI，在 git 操作時觸發(fā)構建操作（上傳小程序版本，設置體驗版）。

說明：

1. 文檔中提供兩種 CI 接入方式：GitHub Actions 和 Drone CI

2. 小程序官方 Docker 構建鏡像：qqminiapp/build:latest

準備工作

獲取 appToken

appToken：用于小程序構建過程中的身份驗證。

• 打開 qq小程序管理端

• 登錄

• 進入設置頁面

• 進入開發(fā)設置頁

• 點擊生成 appToken

• 管理員掃碼

• 得到 appToken

方式一：使用GitHub Actions

使用 Docker 鏡像 + GitHub Actions 實現(xiàn) QQ 小程序持續(xù)集成方案， 適用于 GitHub 的 QQ 小程序項目倉庫。

關于GitHub Actions

GitHub Actions 是 GitHub 官方提供的持續(xù)集成（ CI ）服務，于 2018年10月推出，詳見 官方文檔。

qq小程序CI構建實現(xiàn)

一、 新建項目

GitHub 中新建小程序項目或打開已有小程序項目，可以在下圖中看到 Actions 選項。

二、 編輯GitHub Actions的yaml文件

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

小程序 CI 構建 yml 小例子如下：

name: CI


#寫法一：在push事件時觸發(fā)構建
on: [push] 


#寫法二：在master分支的push操作時觸發(fā)構建
#on:
##  push:
##    branches:
##    - master


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


    runs-on: ubuntu-latest #運行環(huán)境


    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_FIRSTPAGE: pages/index/index
        #PLUGIN_USEPACKAGEJSON: true
        #PLUGIN_NPMBUILD: true
        #PLUGIN_SOURCECODEPATH: ./test

說明：

• env：需要傳入鏡像文件的參數(shù)。其中 PLUGIN_VERSION、PLUGIN_DESC、PLUGIN_APPTOKEN必填，PLUGIN_BUILDUSER 和 PLUGIN_EXPERIENCE 選填。

• PLUGIN_VERSION：小程序版本號。

• PLUGIN_DESC：小程序版本描述。

• PLUGIN_APPTOKEN：從小程序管理端獲取到的 appToken。此處可直接填 appToken，或者可以使用 secrets 變量 secrets.APPTOKEN。secrets 變量設置方式見下圖。

• PLUGIN_BUILDUSER：小程序開發(fā)版的發(fā)布者（小程序管理端->開發(fā)管理->開發(fā)版本的發(fā)布者）。此處使用了 GitHub 提供的 環(huán)境變量github.actor（ 構建者 GitHub 賬號名 ）。

• PLUGIN_EXPERIENCE：表示是否把當前版本設置為體驗版。true：設置為體驗版，false 或不加此參數(shù)：只上傳開發(fā)版本，不會被設置為體驗版。

• PLUGIN_FIRSTPAGE：填寫后，掃小程序二維碼會默認打開此頁面。

• PLUGIN_USEPACKAGEJSON：是否使用項目根目錄下的 package.json 中的版本號 version 和版本描述 uploadDesc。為 true 時，CI 配置中的 version 和 desc 不需要填寫，直接讀取 。package.json 中的版本號和版本描述；為 false 或不填，則需要填寫 CI 配置中的 version、desc。

• PLUGIN_NPMBUILD：是否進行 npm 構建。true: 需要構建 npm (npm install + 構建 npm)；false 或不填：不需要進行 npm 構建

• PLUGIN_SOURCECODEPATH：小程序源碼相對目錄，例如：如果小程序源碼不在根目錄，在 dist 目錄下，如何指定源碼目錄。方法一：如果項目根目錄下存在 project.config.json 文件，可 添加配置 miniprogramRoot: dist 小程序源碼目錄參數(shù)（相對路徑）。方法二：ci 配置文件中增加 PLUGIN_SOURCECODEPATH: ./dist 參數(shù)指定源碼目錄，這種方式需要注意 dist 目錄下得有 project.config.json 文件

三、 執(zhí)行構建操作

編寫好 yml 文件后，執(zhí)行 git push 操作時，GitHub Actions 就會觸發(fā)構建操作了。

如下圖中，打開 actions 菜單，點擊 workflow runs 里面的工作流程，可以看到 GitHub Actions 的詳細執(zhí)行過程。在 build 的執(zhí)行記錄里，可以看到手Q打開體驗版url消息。復制 url 地址在 QQ 中點擊就可以打開體驗版小程序了。

構建完成后，就可以在小程序管理端查看提交的體驗版小程序了。

方式二：使用 Drone CI

Drone CI 是一個開源 CI 工具，其原生支持 Docker，結合小程序 CI 構建 Docker 鏡像能很方便的實現(xiàn)小程序的持續(xù)集成。詳見 Drone官方文檔。

關于 Drone 的構建環(huán)境選擇：

1. Drone 官方提供的云構建環(huán)境（https://cloud.drone.io/）：項目要求是公開的，不支持私有項目

2. 開發(fā)者自己搭建私有構建環(huán)境（ Drone CI 服務器 ）：需要自己搭建 Drone 服務

使用方式

1. 在 GitHub 中新建代碼倉庫

2. 打開 https://cloud.drone.io 或開發(fā)者自己部署的 Drone 網(wǎng)站（ 部署方式詳見 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
        #firstPage: pages/logs/logs
        #usePackageJson: true 
        #npmBuild: true
        #sourceCodePath: ./test

when: # CI構建觸發(fā)時機 event: push branch: master

  **說明：**

    


*   `image`： 需要在stages中使用qq小程序構建鏡像( `qqminiapp/build:latest` )

    
*   `settings`：需要傳入鏡像文件的參數(shù)。其中 appToken 必填；buildUser、experience、firstPage 選填；usePackageJson 選填，當其為 true 時，可不填寫 version 和 desc，當其為 false 或不填，則 version 和desc 必填。

    
*   `version`：小程序版本號

    
*   `desc`：小程序版本描述

    
*   `appToken`：QQ 小程序管理端獲取的 appToken

    
*   `buildUser`：小程序開發(fā)版的發(fā)布者（小程序管理端->開發(fā)管理->開發(fā)版本的發(fā)布者）。推薦填寫 Drone提供的環(huán)境變量。DRONE\_BRANCH：分支名，DRONE\_REPO_OWNER：git賬號名。buildUser 選填，不填默認為“CI”，不同的 buildUser，會在開發(fā)者管理端生成不同版本。可使用 Drone 提供的 [環(huán)境變量](https://docker-runner.docs.drone.io/configuration/environment/variables/)。

    
*   `experience`：表示是否把當前版本設置為體驗版。true：設置為體驗版，false 或不加此參數(shù)：只上傳開發(fā)版本，不會被設置為體驗版。

    
*   `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` 小程序源碼目錄參數(shù)（相對路徑）。方法二：ci 配置文件中增加 `sourceCodePath: ./dist` 參數(shù)指定源碼目錄，這種方式需要注意 dist 目錄下得有 `project.config.json` 文件。

    


5\.  進行 `git push` 操作，在 https://cloud.drone.io/ 中可查看構建過程以及小程序訪問地址。打開 [qq小程序管理端](https://q.qq.com/)，登錄后打開開發(fā)管理，在開發(fā)版本中可以看到 push 后觸發(fā)的 CI 構建上傳的小程序版本。