@tarojs/plugin-mini-ci

@tarojs/plugin-mini-ci

Taro 小程序端构建后支持 CI（持续集成）的插件，支持构建完毕后自动打开小程序开发这个工具、上传作为体验版、生成预览二维码。目前支持（企业）微信、京东、字节、支付宝、钉钉、百度小程序

使用

安装

npm i @tarojs/plugin-mini-ci -D

使用插件

/config/index.js

// 示例，如果你使用 `vs code` 作为开发工具，你还可以使用注释的语法引入插件包含的声明文件，可获得类似于 typescript 的友好提示
/**
 * @typedef { import("@tarojs/plugin-mini-ci").CIOptions } CIOptions
 * @type {CIOptions}
 */
const CIPluginOpt = {
  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 令牌',
  },
  jd: {
    privateKey: '京东小程序秘钥'
  }
  // 版本号
  version: '1.0.0',
  // 版本发布描述
  desc: '版本描述',
}
const config = {
  plugins: [['@tarojs/plugin-mini-ci', CIPluginOpt]],
}

除了给插件传入对象，你也可以传入一个异步函数，在编译时动态返回相关配置。

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 令牌"
      },
      jd: {
        privateKey: '京东小程序秘钥'
      }
      // 版本号
      version: "1.0.0",
      // 版本发布描述
      desc: "版本描述"
  }
}

const config = {
  plugins: [
    [ "@tarojs/plugin-mini-ci", CIPluginFn ]
  ]
}

作为选项配合 build 命令使用

package.json 的 scripts 字段使用命令参数

{
  "scripts": {
    //  构建完后自动“打开开发者工具”
    "build:weapp": "taro build --type weapp --open",
    //  构建完后自动“上传代码作为开发版并生成预览二维码”
    "build:weapp:preview": "taro build --type weapp --preview",
    //  构建完后自动“上传代码作为体验版”
    "build:weapp:upload": "taro build --type weapp --upload",
    //  构建完后自动“上传 dist/xxx 目录的代码作为体验版”，`--projectPath` 参数 适用于 taro 和 原生混合的场景
    "build:weapp:upload": "taro build --type weapp --upload --projectPath dist/xxx"
  },
  "taroConfig": {
    "version": "1.0.0",
    "desc": "上传描述"
  }
}

由上面的示例可知，插件为 taro cli 命令扩展了 4 个选项：

• --open 打开开发者工具，类似于网页开发中自动打开谷歌浏览器
• --preview 上传代码作为开发版并生成预览二维码
• --upload 上传代码作为体验版

此 3 个选项在一条命令里不能同时使用（互斥）

• --projectPath 指定要操作（打开、预览、上传）的目录路径，默认情况下是操作构建后目录路径，即 outputRoot 选项；

此选项必须搭配上述三个选项之一一起使用；

此选项优先级为：终端传入的--projectPath > CI 配置的projectPath 选项 > outputRoot 选项。

作为命令单独使用

{
  "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 选项

Hooks 使用

在插件执行完 预览、上传 操作后，插件会触发 2 个钩子事件：

事件名	传递参数对象	说明
onPreviewComplete	详细见下文	CI 执行预览后触发
onUploadComplete	详细见下文	CI 执行上传后触发

两个钩子被触发时传入的数据对象描述如下

interface HooksData {
  /** 是否预览、构建成功 */
  success: boolean
  data: {
    /** 当前构建的小程序平台 */
    platform: string
    /** 预览码本地路径 */
    qrCodeLocalPath: string
    /** 预览码内容 */
    qrCodeContent: string
    /** 插件传递的预览版本号 */
    version: string
    /** 插件传递的描述文本 */
    desc: string
    /** 预览或上传的目录路径 */
    projectPath: string
  }
  /** 错误对象 */
  error?: Error
}

你可以写一个自定义插件，来接收上述 2 个事件传递的值：

// 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)
      // 你可以在这里发送钉钉或者飞书消息
    },
  })
}

然后把自己写的插件配置应用起来：

// 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	✅	✅	✅
jd	❌	✅	✅

ps: 各平台上传都是支持的，只是不一定会输出二维码

企业微信和微信的各项参数是一样的，共用一个配置

API

插件配置

参数	类型	说明
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 配置

参数	类型	说明
appid	string	小程序/小游戏项目的 appid
privateKeyPath	string	私钥文件在项目中的相对路径，在获取项目属性和上传时用于鉴权使用
devToolsInstallPath	string	微信开发者工具安装路径，如果你安装微信开发者工具时选的默认路径，则不需要传入此参数 (选填)
projectPath	string	上传的小程序的路径（默认取的 outputRoot）（3.6.0 版本已废弃）
ignores	string[]	上传需要排除的目录 (选填)
robot	number	指定使用哪一个 ci 机器人，可选值：1 ~ 30(选填，3.6.0 版本开始支持)
setting	Object	预览和上传时的编译设置，具体见下表 (选填，3.6.2 版本开始支持)

编译设置选项说明

参数	类型	说明
es6	boolean	对应于微信开发者工具的 "es6 转 es5"
es7	boolean	对应于微信开发者工具的 "增强编译"
disableUseStrict	boolean	"增强编译" 开启时，是否禁用 JS 文件严格模式，默认为 false
minifyJS	boolean	上传时压缩 JS 代码
minifyWXML	boolean	上传时压缩 WXML 代码
minifyWXSS	boolean	上传时压缩 WXSS 代码
minify	boolean	上传时压缩所有代码，对应于微信开发者工具的 "上传时压缩代码"
codeProtect	boolean	对应于微信开发者工具的 "上传时进行代码保护"
autoPrefixWXSS	boolean	对应于微信开发者工具的 "上传时样式自动补全"

官方 CI 文档点这里

头条小程序 CI 配置

参数	类型	说明
email	string	字节小程序邮箱
password	string	字节小程序密码

官方 CI 文档点这里

支付宝小程序 CI 配置

参数	类型	说明
appid	string	小程序 appid(3.6.0 之前参数名是 appId ， 3.6.0 开始统一成appid)
toolId	string	工具 id，查看这里复制
privateKeyPath	string	密钥文件相对项目根目录的相对路径，私钥可通过支付宝开放平台开发助手生成
privateKey	string	私钥文本内容，生成方式同上 (privateKeyPath 和 privateKey 之间必须要填写其中一个；3.6.0 版本开始支持)
devToolsInstallPath	string	小程序开发者工具安装路径 (选填，3.6.0 版本开始支持)
clientType	string	上传的终端，终端类型见下表（选填，默认值 alipay）
deleteVersion	string	在上传过程中删除指定的版本，即使该版本正在构建中或不存在。记录已上传的版本并使用这个参数能有效避免上传版本无法超过 20 个的问题（选填，默认自动删除上一个版本。可设置0.0.0，关闭自动删除）

终端类型值及其含义：

alipay: 支付宝

ampe：AMPE

amap：高德

genie：天猫精灵

alios：ALIOS

uc：UC

quark：夸克

koubei：口碑

alipayiot：IoT

cainiao：菜鸟

alihealth：阿里健康

health:  阿里医院

官方 CI 文档点这里

钉钉小程序 CI 配置（3.6.0 版本开始支持）

参数	类型	说明
appid	string	钉钉小程序 appid，即钉钉开放平台后台应用管理的 MiniAppId 选项（必填）
token	string	令牌，从钉钉后台获取（必填）
devToolsInstallPath	string	小程序开发者工具安装路径（选填）

taro 集成的钉钉 CI 使用了钉钉官方仓库中的 dingtalk-miniapp-opensdk 包，查阅源码封装而成

百度小程序 CI 配置

参数	类型	说明
token	string	有该小程序发布权限的登录密钥
minSwanVersion	string	最低基础库版本，不传默认为 3.350.6

官方 CI 文档点这里

京东小程序 CI 配置

参数	类型	说明
privateKey	string	秘钥字符串
robot	number	指定使用哪一个 ci 机器人，可选值：1 ~ 30
ignores	string[]	指定需要排除的规则。无需配置以“.”开头的隐藏文件，它们将默认被忽略，如“.git”

官方 CI 文档点这里

完整 ts 接口描述

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
  /** 京东小程序配置，官方文档地址：https://mp-docs.jd.com/doc/dev/devtools/1597 */
  jd?: JdConfig
}

export type ProjectType = 'miniProgram' | 'miniGame' | 'miniProgramPlugin' | 'miniGamePlugin'

/** 微信小程序配置 */
export interface WeappConfig {
  /** 小程序/小游戏项目的 appid */
  appid: string
  /** 私钥文件路径，在获取项目属性和上传时用于鉴权使用 */
  privateKeyPath: string
  /** 微信开发者工具安装路径 */
  devToolsInstallPath?: string
  /** 类型，默认 miniProgram 小程序 */
  type?: ProjectType
  /** 上传需要排除的目录 */
  ignores?: Array<string>
  /** 指定使用哪一个 ci 机器人，可选值：1 ~ 30 */
  robot?: number
    /** 预览和上传时的编译设置 */
  setting?: {
    /** 对应于微信开发者工具的 "es6 转 es5" */
    es6: boolean
    /** 对应于微信开发者工具的 "增强编译" */
    es7: boolean
    /** "增强编译" 开启时，是否禁用 JS 文件严格模式，默认为 false */
    disableUseStrict: boolean
    /** 上传时压缩 JS 代码 */
    minifyJS: boolean
    /** 上传时压缩 WXML 代码 */
    minifyWXML: boolean
    /** 上传时压缩 WXSS 代码 */
    minifyWXSS: boolean
    /** 上传时压缩所有代码，对应于微信开发者工具的 "上传时压缩代码" */
    minify: boolean
    /** 对应于微信开发者工具的 "上传时进行代码保护" */
    codeProtect: boolean
    /** 对应于微信开发者工具的 "上传时样式自动补全" */
    autoPrefixWXSS: boolean
  }
}

/** 头条小程序配置 */
export interface TTConfig {
  /** 绑定的邮箱账号 */
  email: string
  /** 密码 */
  password: string
}

/** 终端类型 */
export type AlipayClientType = /** 支付宝 */
  | 'alipay'
  /** AMPE */
  | 'ampe'
  /** 高德 */
  | 'amap'
  /** 天猫精灵 */
  | 'genie'
  /** ALIOS */
  | 'alios'
  /** UC */
  | 'uc'
  /** 夸克 */
  | 'quark'
  /** 口碑 */
  | 'koubei'
  /** loT */
  | 'alipayiot'
  /** 菜鸟 */
  | 'cainiao'
  /** 阿里健康 (医蝶谷) */
  | 'alihealth'
  /** 阿里医院 */
  | 'health'

/** 支付宝系列小程序配置 */
export interface AlipayConfig {
  /** 小程序 appid */
  appid: string
  /** 工具 id */
  toolId: string
  /** 私钥文件路径，在获取项目属性和上传时用于鉴权使用 (privateKeyPath 和 privateKey 之间必须要填写其中一个) */
  privateKeyPath: string
  /** 私钥文本内容，在获取项目属性和上传时用于鉴权使用 (privateKeyPath 和 privateKey 之间必须要填写其中一个) */
  privateKey: string
  /** 小程序开发者工具安装路径 */
  devToolsInstallPath?: string
  /** 上传的终端，默认 alipay */
  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
  /** 最低基础库版本，不传默认为 3.350.6 */
  minSwanVersion?: string
}

/** 京东小程序配置 */
export interface JdConfig {
  /** 秘钥信息 */
  privateKey: string
  /** 指定使用哪一个 ci 机器人，可选值：1 ~ 30 */
  robot?: number
  /** 指定需要排除的规则。无需配置以“.”开头的隐藏文件，它们将默认被忽略，如“.git” */
  ignores?: string[]
}