@tarojs/plugin-mini-ci 3.5.10 → 3.6.0-alpha.0

package/README.md

@@ -1,15 +1,17 @@
 # @tarojs/plugin-mini-ci
 
-> Taro 小程序端构建后支持CI（持续集成）的插件， 支持构建完毕后自动打开小程序开发这个工具、上传作为体验版、生成预览二维码. 目前暂时仅支持微信、字节、支付宝、百度小程序
+> Taro 小程序端构建后支持CI（持续集成）的插件， 支持构建完毕后自动打开小程序开发这个工具、上传作为体验版、生成预览二维码. 目前支持（企业）微信、字节、支付宝、钉钉、百度小程序
 
 ## 使用
 
 ### 安装
-```
+
+```sh
 npm i @tarojs/plugin-mini-ci -D
 ```
 
 ### 使用插件
+
 `/config/index.js`
 
 ```js
@@ -28,10 +30,14 @@ const CIPluginOpt = {
         password: "字节小程序密码"
     },
     alipay: {
-      appId: "支付宝小程序appId",
+      appid: "支付宝小程序appid",
       toolId: "工具id",
       privateKeyPath: "密钥文件相对项目根目录的相对路径，例如 key/pkcs8-private-pem"
     },
+    dd: {
+        appid: "钉钉小程序appid,即钉钉开放平台后台应用管理的 MiniAppId 选项",
+        token: "令牌，从钉钉后台获取"
+    },
     swan: {
       token: "鉴权需要的token令牌"
     },
@@ -47,7 +53,51 @@ const config = {
 }
 ```
 
-### 配置命令
+除了给插件传入对象， 你也可以传入一个异步函数，在编译时动态返回相关配置。
+
+```js
+const CIPluginFn = async () => {
+  // 可以在这里做一些异步事情， 比如请求接口获取配置
+  /**
+   * @typedef { import("@tarojs/plugin-mini-ci").CIOptions } CIOptions
+   * @type {CIOptions}
+   */
+  return {
+      weapp: {
+          appid: "微信小程序appid",
+          privateKeyPath: "密钥文件相对项目根目录的相对路径，例如 key/private.appid.key"
+      },
+      tt: {
+          email: "字节小程序邮箱",
+          password: "字节小程序密码"
+      },
+      alipay: {
+        appid: "支付宝小程序appid",
+        toolId: "工具id",
+        privateKeyPath: "密钥文件相对项目根目录的相对路径，例如 key/pkcs8-private-pem"
+      },
+      dd: {
+        appid: "钉钉小程序appid,即钉钉开放平台后台应用管理的 MiniAppId 选项"
+        token: "令牌，从钉钉后台获取"
+      },
+      swan: {
+        token: "鉴权需要的token令牌"
+      },
+      // 版本号
+      version: "1.0.0",
+      // 版本发布描述
+      desc: "版本描述"
+  }
+}
+
+const config = {
+  plugins: [
+    [ "@tarojs/plugin-mini-ci", CIPluginFn ]
+  ]
+}
+```
+
+### 作为选项配合 build 命令使用
 
 `package.json` 的 `scripts` 字段使用命令参数
 
@@ -56,10 +106,12 @@ const config = {
     "scripts": {
             //  构建完后自动 “打开开发者工具”
            "build:weapp": "taro build --type weapp --open",
+            //  构建完后自动 “上传代码作为开发版并生成预览二维码”     
+           "build:weapp:preview": "taro build --type weapp --preview",
             //  构建完后自动“上传代码作为体验版”
            "build:weapp:upload": "taro build --type weapp --upload",
-            //  构建完后自动 “上传代码作为开发版并生成预览二维码”     
-           "build:weapp:preview": "taro build --type weapp --preview"
+            //  构建完后自动“上传 dist/xxx 目录的代码作为体验版”， `--projectPath` 参数 适用于 taro 和 原生混合的场景
+           "build:weapp:upload": "taro build --type weapp --upload --projectPath dist/xxx"
     },
     "taroConfig": {
         "version": "1.0.0",
@@ -67,39 +119,174 @@ const config = {
     }
 }
 ```
-由上面的示例可知，插件为taro cli命令扩展了3个选项：
+
+由上面的示例可知，插件为taro cli命令扩展了4个选项：
 
 - --open
 打开开发者工具，类似于网页开发中自动打开谷歌浏览器
-- --upload
-上传代码作为体验版
 - --preview
 上传代码作为开发版并生成预览二维码
+- --upload
+上传代码作为体验版
 
-此3个选项在一条命令里不能同时使用
+此3个选项在一条命令里不能同时使用（互斥）
 
-## API
+- --projectPath
+指定要操作（打开、预览、上传）的目录路径， 默认情况下是操作构建后目录路径，即 [outputRoot选项](https://taro-docs.jd.com/taro/docs/next/config-detail#outputroot)；
+
+此选项必须搭配上述三个选项之一一起使用；
+
+此选项优先级为： 终端传入的`--projectPath` > CI配置的`projectPath` 选项 > [outputRoot选项](https://taro-docs.jd.com/taro/docs/next/config-detail#outputroot)。
+
+### 作为命令单独使用
+
+```json
+{
+    "scripts": {
+            //  直接 “打开开发者工具并载入项目”
+           "build:weapp": "taro open --type weapp  --projectPath dist/xxx",
+            //  直接 “上传代码作为开发版并生成预览二维码”     
+           "build:weapp:preview": "taro preview --type weapp",
+            //  直接“上传代码作为体验版”
+           "build:weapp:upload": "taro upload --type weapp",
+            //  上传指定目录代码作为体验版
+           "build:weapp:upload2": "taro upload --type weapp --projectPath dist/xxx",
+    },
+    "taroConfig": {
+        "version": "1.0.0",
+        "desc": "上传描述"
+    }
+}
+```
+
+由上面的示例可知，插件额外新增了3个独立命令，让你可以直接操作指定目录。适用于把 `taro` 作为项目一部分的使用场景。
+
+当直接作为命令使用时，有两个选项：
+
+- --type
+传入平台名称
+- --projectPath
+传入路径。 此选项优先级为： 终端传入的`--projectPath` > CI配置的`projectPath` 选项 > [outputRoot选项](https://taro-docs.jd.com/taro/docs/next/config-detail#outputroot)
+
+### Hooks 使用
 
+在插件执行完  `预览`、`上传` 操作后， 插件会触发2个钩子事件：
+
+| 事件名 | 传递参数对象 | 说明 |
+| :--- | :--- | :--- |
+| onPreviewComplete | 详细见下文 | CI 执行预览后触发 |
+| onUploadComplete | 详细见下文| CI 执行上传后触发 |
+
+两个钩子被触发时传入的数据对象描述如下
+
+```ts
+interface HooksData {
+  /** 是否预览、构建成功 */
+  success: boolean;
+  data: {
+    /** 当前构建的小程序平台 */
+    platform: string;
+    /** 预览码本地路径 */
+    qrCodeLocalPath: string;
+    /** 预览码内容 */
+    qrCodeContent: string;
+    /** 插件传递的预览版本号 */
+    version: string;
+    /** 插件传递的描述文本 */
+    desc: string;
+    /** 预览或上传的目录路径 */
+    projectPath: string;
+  },
+  /** 错误对象 */
+  error?: Error;
+}
+```
+
+你可以写一个自定义插件，来接收上述2个事件传递的值：
+
+```js
+// config/test.js
+module.exports = function(ctx) {
+    ctx.register({
+        name: 'onPreviewComplete',
+        fn: ({success, data, error}) => {
+            console.log('接收预览后数据', success, data, error)
+            // 你可以在这里发送钉钉或者飞书消息
+        }
+    })
+    ctx.register({
+        name: 'onUploadComplete',
+        fn: ({success, data, error}) => {
+            console.log('接收上传后数据', success, data, error)
+            // 你可以在这里发送钉钉或者飞书消息
+        }
+    })
+}
+```
+
+然后把自己写的插件配置应用起来：
+
+```js
+// config/index.js
+const config = {
+  
+  plugins: [
+    ["@tarojs/plugin-mini-ci", CI插件参数],
+    // 应用自己写的插件
+    require('path').join(__dirname, './test' )
+  ],
+  ... 其他配置省略
+ 
+}
+
+module.exports = function (merge) {
+  if (process.env.NODE_ENV === 'development') {
+    return merge({}, config, require('./dev'))
+  }
+  return merge({}, config, require('./prod'))
+}
+```
+
+### 各平台 支持的功能情况对比
+
+| 平台/功能 | 自动打开IDE  | 输出预览二维码 | 输出体验二维码  |
+| :---     | :---       | :---         | :---          |
+| weapp    | ✅         | ✅            |✅             |
+| qywx     | ✅         | ✅            |✅             |
+| tt       | ✅         | ✅            |✅             |
+| alipay   | ✅         | ✅            |✅             |
+| dd       | ✅         | ✅            |❌             |
+| swan     | ✅         | ✅            |✅             |
+
+> ps: 各平台上传都是支持的，只是不一定会输出二维码
+
+> 企业微信和微信的各项参数是一样的，共用一个配置
+
+## API
 
 ### 插件配置
 
 | 参数 | 类型 | 说明 |
 | :--- | :--- | :--- |
-| weapp | Object | 微信小程序CI配置 |
+| weapp | Object | （企业）微信小程序CI配置 |
 | tt | Object | 头条小程序配置 |
 | alipay | Object | 支付宝小程序配置 |
+| dd | Object | 钉钉小程序配置（3.6.0 版本开始支持） |
 | swan | Object | 百度小程序配置 |
 | version | string | 上传版本号，不传时默认读取package.json下的taroConfig下的version字段 |
 | desc | string | 上传时的描述信息，不传时默认读取package.json下的taroConfig下的desc字段 |
+| projectPath | string | 目标项目目录，对所有小程序生效（不传默认取 outputRoot 字段 ）（3.6.0 版本开始支持） |
+
+### （企业）微信小程序CI配置
 
-### 微信小程序CI配置
 | 参数 | 类型 | 说明 |
 | :--- | :--- | :--- |
 | appid | string | 小程序/小游戏项目的 appid |
 | privateKeyPath | string | 私钥文件在项目中的相对路径，在获取项目属性和上传时用于鉴权使用|
-| devToolsInstallPath | string | 微信开发者工具安装路径，如果你安装微信开发者工具时选的默认路径，则不需要传入此参数 |
-| projectPath | string | 上传的小程序的路径（默认取的 outputPath ） |
+| devToolsInstallPath | string | 微信开发者工具安装路径，如果你安装微信开发者工具时选的默认路径，则不需要传入此参数(选填) |
+| projectPath | string | 上传的小程序的路径（默认取的 outputRoot ）（3.6.0 版本已废弃） |
 | ignores | string[] | 上传需要排除的目录(选填) |
+| robot | number | 指定使用哪一个 ci 机器人，可选值：1 ~ 30(选填, 3.6.0 版本开始支持) |
 
 官方CI文档[点这里](https://developers.weixin.qq.com/miniprogram/dev/devtools/ci.html)
 
@@ -116,10 +303,12 @@ const config = {
 
 | 参数 | 类型 | 说明 |
 | :--- | :--- | :--- |
-| appId | string | 小程序appId |
-| toolId | string | 工具id，生成方式[查看这里](https://opendocs.alipay.com/mini/miniu/api#%E5%88%9D%E5%A7%8B%E5%8C%96%E9%85%8D%E7%BD%AE%EF%BC%88%E4%B9%8B%E5%89%8D%E7%9A%84%E6%96%B9%E5%BC%8F%EF%BC%8C%E6%8E%A8%E8%8D%90%E4%BD%BF%E7%94%A8%20miniu%20login%EF%BC%89) |
-| privateKeyPath | string | 密钥文件相对项目根目录的相对路径, 支付宝生产的私钥文件名一般是 pkcs8-private-pem |
-| clientType | string | 上传的终端,终端类型见下表（默认值alipay） |
+| appid | string | 小程序appid(`3.6.0` 之前参数名是 `appId` ， `3.6.0` 开始统一成`appid`) |
+| toolId | string | 工具id，[查看这里复制](https://open.alipay.com/dev/workspace/key-manage/tool) |
+| privateKeyPath | string | 密钥文件相对项目根目录的相对路径, 私钥可通过[支付宝开放平台开发助手](https://opendocs.alipay.com/common/02kipl)生成 |
+| privateKey | string | 私钥文本内容, 生成方式同上(privateKeyPath和privateKey之间必须要填写其中一个； 3.6.0 版本开始支持) |
+| devToolsInstallPath | string | 小程序开发者工具安装路径(选填, 3.6.0 版本开始支持) |
+| clientType | string | 上传的终端,终端类型见下表（选填，默认值alipay） |
 
 ```
 终端类型值及其含义：
@@ -138,8 +327,6 @@ uc：UC
 
 quark：夸克
 
-taobao：淘宝
-
 koubei：口碑
 
 alipayiot：IoT
@@ -147,9 +334,21 @@ alipayiot：IoT
 cainiao：菜鸟
 
 alihealth：阿里健康
+
+health:  阿里医院
 ```
 
-官方CI文档[点这里](https://opendocs.alipay.com/mini/miniu/api)
+官方CI文档[点这里](https://opendocs.alipay.com/mini/02q29z)
+
+### 钉钉小程序CI配置（3.6.0 版本开始支持）
+
+| 参数 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| appid | string | 钉钉小程序appid,即钉钉开放平台后台应用管理的 MiniAppId 选项（必填） |
+| token | string | 令牌，从钉钉后台获取 （必填） |
+| devToolsInstallPath | string | 小程序开发者工具安装路径（选填）  |
+
+`taro` 集成的钉钉CI使用了[钉钉官方仓库](https://github.com/open-dingtalk/dingtalk-design-cli)中的 `dingtalk-miniapp-opensdk` 包，查阅源码封装而成
 
 ### 百度小程序CI配置
 
@@ -160,41 +359,56 @@ alihealth：阿里健康
 
 官方CI文档[点这里](https://smartprogram.baidu.com/docs/develop/devtools/commandtool/)
 
-### ts 接口描述
+### 完整 ts 接口描述
+
 ```ts
-export interface IOptions {
-  version?: string;
-  desc?: string;
-  weapp?: WeappConfig;
-  tt?: TTConfig;
-  alipay?: AlipayConfig;
-  swan?: SwanConfig;
+export interface CIOptions {
+  /** 发布版本号，默认取 package.json 文件的 taroConfig.version 字段 */
+  version?: string
+  /** 版本发布描述， 默认取 package.json 文件的 taroConfig.desc 字段 */
+  desc?: string
+  /** 目标项目目录，对所有小程序生效（不传默认取 outputRoot 字段 ） */
+  projectPath?: string
+  /** 微信小程序CI配置, 官方文档地址：https://developers.weixin.qq.com/miniprogram/dev/devtools/ci.html */
+  weapp?: WeappConfig
+  /** 头条小程序配置, 官方文档地址：https://microapp.bytedance.com/docs/zh-CN/mini-app/develop/developer-instrument/development-assistance/ide-order-instrument */
+  tt?: TTConfig
+  /** 支付宝系列小程序配置，官方文档地址： https://opendocs.alipay.com/mini/miniu/api */
+  alipay?: AlipayConfig
+  /** 钉钉小程序配置 */
+  dd?: DingtalkConfig
+  /** 百度小程序配置, 官方文档地址：https://smartprogram.baidu.com/docs/develop/devtools/commandtool/ */
+  swan?: SwanConfig
 }
 
+export type ProjectType = 'miniProgram' | 'miniGame' | 'miniProgramPlugin' | 'miniGamePlugin';
+
 /** 微信小程序配置 */
 export interface WeappConfig {
   /** 小程序/小游戏项目的 appid */
-  appid: string;
-  /** 私钥，在获取项目属性和上传时用于鉴权使用(必填) */
-  privateKeyPath: string;
+  appid: string
+  /** 私钥文件路径，在获取项目属性和上传时用于鉴权使用 */
+  privateKeyPath: string
   /** 微信开发者工具安装路径 */
-  devToolsInstallPath?: string;
-  /** 上传的小程序的路径（默认 outputPath ） */
-  projectPath?: string;
+  devToolsInstallPath?: string
   /** 类型，默认miniProgram 小程序 */
-  type?: ProjectType;
+  type?: ProjectType
   /** 上传需要排除的目录 */
-  ignores?: Array<string>;
+  ignores?: Array<string>
+  /** 指定使用哪一个 ci 机器人，可选值：1 ~ 30 */
+  robot?: number
 }
 
 /** 头条小程序配置 */
 export interface TTConfig {
-  email: string;
-  password: string;
+  /** 绑定的邮箱账号 */
+  email: string
+  /** 密码 */
+  password: string
 }
 
 /** 终端类型 */
-export type ClientType =
+export type AlipayClientType =
 /** 支付宝 */'alipay' |
 /** AMPE */'ampe' |
 /** 高德 */'amap' |
@@ -202,31 +416,56 @@ export type ClientType =
 /** ALIOS */ 'alios'|
 /** UC */'uc'|
 /** 夸克 */ 'quark'|
-/** 淘宝 */ 'taobao'|
 /** 口碑 */'koubei' |
 /** loT */'alipayiot'|
 /** 菜鸟 */'cainiao' |
-/** 阿里健康 */ 'alihealth'
+/** 阿里健康(医蝶谷) */ 'alihealth'|
+/** 阿里医院 */ 'health'
 
 /** 支付宝系列小程序配置 */
 export interface AlipayConfig {
-  /** 小程序appId */
-  appId: string;
+  /** 小程序appid */
+  appid: string
   /** 工具id */
-  toolId: string;
-  /** 工具私钥 */
-  privateKey: string;
-  /** 服务代理地址（可选） */
-  proxy?: string;
+  toolId: string
+  /** 私钥文件路径，在获取项目属性和上传时用于鉴权使用(privateKeyPath和privateKey之间必须要填写其中一个) */
+  privateKeyPath: string
+  /** 私钥文本内容，在获取项目属性和上传时用于鉴权使用(privateKeyPath和privateKey之间必须要填写其中一个) */
+  privateKey: string
+  /** 小程序开发者工具安装路径 */
+  devToolsInstallPath?: string
   /** 上传的终端, 默认alipay */
-  clientType?: ClientType;
+  clientType?: AlipayClientType
+}
+
+export type DingtalkProjectType =
+/** 第三方个人应用 */
+'dingtalk-personal'|
+/** 第三方企业应用 */
+'dingtalk-biz-isv'|
+/** 企业内部应用 */
+'dingtalk-biz'|
+/** 企业定制应用 */
+'dingtalk-biz-custom'|
+/** 工作台组件 */
+'dingtalk-biz-worktab-plugin'
+export interface DingtalkConfig {
+  /** 钉钉小程序appid,即钉钉开放平台后台应用管理的 MiniAppId 选项（必填） */
+  appid: string
+  /** 令牌，从钉钉后台获取 */
+  token: string
+  /** 小程序开发者工具安装路径 */
+  devToolsInstallPath?: string
+  /** 钉钉应用类型， 默认为:'dingtalk-biz' (企业内部应用) */
+  projectType?: DingtalkProjectType
 }
 
 /** 百度小程序配置 */
 export interface SwanConfig {
   /** 有该小程序发布权限的登录密钥 */
-  token: string;
+  token: string
   /** 最低基础库版本, 不传默认为 3.350.6 */
-  minSwanVersion?: string;
+  minSwanVersion?: string
 }
+
 ```