小程序 CI 構(gòu)建

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

說明：

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

2. 小程序官方 Docker 構(gòu)建鏡像：qqminiapp/build:latest

準(zhǔn)備工作

獲取 appToken

appToken：用于小程序構(gòu)建過程中的身份驗證。

• 打開 qq小程序管理端

• 登錄

• 進入設(shè)置頁面

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

• 點擊生成 appToken

• 管理員掃碼

• 得到 appToken

方式一：使用GitHub Actions

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

關(guān)于GitHub Actions

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

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

一、 新建項目

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

二、 編輯GitHub Actions的yaml文件

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

小程序 CI 構(gòu)建 yml 小例子如下：

name: CI


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


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


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


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


    steps:

    
    #第一步：獲取小程序源碼
    - name: Checkout 
      uses: actions/checkout@master

      
    #第二步：上傳小程序版本到管理端，并將此版本設(shè)置為體驗版（設(shè)置體驗版可選）
    - name: Build 
      uses: docker://qqminiapp/build:latest 
      env: 
        PLUGIN_VERSION: 1.0.0
        PLUGIN_DESC: CI自動構(gòu)建上傳
        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 變量設(shè)置方式見下圖。

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

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

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

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

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

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

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

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

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

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

方式二：使用 Drone CI

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

關(guān)于 Drone 的構(gòu)建環(huán)境選擇：

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

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

使用方式

1. 在 GitHub 中新建代碼倉庫

2. 打開 https://cloud.drone.io 或開發(fā)者自己部署的 Drone 網(wǎng)站（ 部署方式詳見 https://docs.drone.io/installation/runners/ ），使用 GitHub 賬號登錄

3. 在登錄后的界面中可以看到構(gòu)建記錄

   

4. 在小程序項目根目錄編寫 .drone.yml 的 CI 配置文件

   小程序 CI 構(gòu)建小例子如下：

   
   # yml小例子
   kind: pipeline
   name: default
   
   
   
   
   steps:
    - name: CI Auto Build
      image: qqminiapp/build:latest
      settings:
        version: 1.0.0
        desc: CI自動構(gòu)建上傳 
        appToken: xxx
        buildUser: ${DRONE_REPO_OWNER} 
        experience: true
        #firstPage: pages/logs/logs
        #usePackageJson: true 
        #npmBuild: true
        #sourceCodePath: ./test

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

  **說明：**

    


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

    
*   `settings`：需要傳入鏡像文件的參數(shù)。其中 appToken 必填；buildUser、experience、firstPage 選填；usePackageJson 選填，當(dāng)其為 true 時，可不填寫 version 和 desc，當(dāng)其為 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`：表示是否把當(dāng)前版本設(shè)置為體驗版。true：設(shè)置為體驗版，false 或不加此參數(shù)：只上傳開發(fā)版本，不會被設(shè)置為體驗版。

    
*   `firstPage`：掃描小程序二維碼，默認打開的頁面。

    
*   `usePackageJson`：是否使用小程序項目根目錄下的 `package.json` 中的版本號 version 和版本描述 uploadDesc 。為 true 時，ci 配置文件中的version 和 desc 不生效，直接讀取 `package.json` 中的版本號和版本描述；為 false 或不填，則需要填寫 CI 配置中的 version、desc

    
*   `npmBuild`：是否進行 npm 構(gòu)建。true: 需要構(gòu)建 npm (npm install + 構(gòu)建 npm)；false 或不填：不需要進行 npm 構(gòu)建

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

    


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