企业官网建设流程全解析

Taro 小程序 CI/CD 实战：使用 @tarojs/plugin-mini-ci 自动打开开发者工具、预览与上传体验版

【免费下载链接】taro开放式跨端跨框架解决方案，支持使用 React/Vue/Nerv 等框架来开发微信/京东/百度/支付宝/字节跳动/ QQ 小程序/H5/React Native 等应用。 https://taro.zone/项目地址: https://gitcode.com/NervJS/taro

本指南基于 Taro 官方仓库中的 packages/taro-plugin-mini-ci/README.md，系统讲解@tarojs/plugin-mini-ci这一构建后 CI 插件的安装、配置、命令使用与 Hooks 扩展。读完本文，你将掌握如何让 Taro 小程序在taro build构建完成后自动打开（企业）微信、字节、支付宝、钉钉、百度、京东等平台开发者工具，自动上传代码作为开发版/体验版并生成预览二维码，从而把「构建 → 预览 → 上传」这一繁琐链路完全交给脚本与 CI 流水线。

一、插件是什么：构建后自动化的 CI 能力

@tarojs/plugin-mini-ci是 Taro 官方提供的小程序端 CI（持续集成）插件，核心定位是：在 Taro 小程序构建完毕后自动执行三类动作：

1. 自动打开对应平台的小程序开发者工具（类似网页开发中自动打开浏览器）；
2. 上传代码作为「开发版」并生成预览二维码；
3. 上传代码作为「体验版」。

目前支持（企业）微信、京东、字节（抖音）、支付宝、钉钉、百度小程序。从仓库源码看，插件按平台拆分了独立实现类：src/WeappCI.ts、src/TTCI.ts、src/AlipayCI.ts、src/DingtalkCI.ts、src/SwanCI.ts、src/JdCI.ts，它们统一继承自抽象基类 src/BaseCi.ts，基类定义了init()、open()、upload()、preview()四个抽象方法以及版本号、描述、项目路径的公共处理逻辑。

各平台底层依赖的 CI SDK 以 optional peerDependencies 形式声明在 package.json 中：miniprogram-ci（微信）、tt-ide-cli（字节）、minidev（支付宝）、dingtalk-miniapp-opensdk（钉钉）、jd-miniprogram-ci（京东），使用时只需按需安装对应平台的 SDK 即可，互不干扰。

二、安装插件

在 Taro 项目根目录执行：

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

由于平台 SDK 是按需可选依赖，还需要根据实际使用平台额外安装对应依赖，例如微信平台：

npm i miniprogram-ci -D

如果未安装对应平台依赖，插件运行时会打印类似请安装依赖：miniprogram-ci的错误提示并终止进程（见 WeappCI.ts）。

三、在 config/index.js 中接入插件

3.1 传入配置对象

在 Taro 项目的 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]], }

3.2 传入异步函数动态获取配置

除了对象，插件还支持传入一个异步函数，在编译时动态返回配置。这种写法适合从远程接口、环境变量或 CI 流水线注入的凭据中动态取得配置：

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 ] ] }

从源码 src/index.ts 可以看到，插件在执行动作时会判断配置是函数还是对象：const pluginOpts = typeof _pluginOpts === 'function' ? await _pluginOpts() : _pluginOpts，因此异步函数在动作执行前才会被调用，每次构建可拿到最新配置。

3.3 配置校验

插件通过ctx.addPluginOptsSchema注册了 Joi 校验规则（见 src/index.ts），配置必须是一个「函数」或「包含合法字段的对象」，否则会直接报错。例如weapp.appid、weapp.privateKeyPath、tt.email、tt.password、dd.token、dd.appid、swan.token、jd.privateKey均为必填项；支付宝的clientType仅允许枚举值，deleteVersion必须符合x.y.z的版本号格式。

四、作为 build 命令选项使用（构建后自动执行）

@tarojs/plugin-mini-ci为taro build命令扩展了 4 个选项，在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": "上传描述" } }

4.1 扩展的选项说明

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

使用要点：

• --open、--preview、--upload三个选项在一条命令里不能同时使用（互斥）。从源码 src/index.ts 可以看出，插件在build命令的onBuildComplete（兼容旧的onBuildFinish）回调里用switch (true)依次匹配三个布尔参数，只取第一个命中的动作执行；
• --projectPath必须搭配上述三个选项之一一起使用；
• --projectPath优先级为：终端传入的--projectPath> CI 配置的projectPath选项 >outputRoot选项。对应源码 src/index.ts：projectPath = projectPath || pluginOpts.projectPath || ctx.paths.outputPath，相对路径会基于项目根目录（appPath）解析，且会校验目录存在性，不存在则报错退出。

五、作为独立命令单独使用（操作指定目录）

@tarojs/plugin-mini-ci还额外注册了 3 个独立命令taro open、taro preview、taro upload（见 src/index.ts），让你可以不经过构建流程，直接操作任意指定目录，适用于把 taro 作为项目一部分（例如 Taro 与原生小程序代码混合）的场景：

{ "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": "上传描述" } }

当直接作为命令使用时，有两个选项：

独立命令同样遵循上述路径解析与校验逻辑。平台的类型映射同样见 src/index.ts：weapp与qywx共用微信实现类，alipay与iot共用支付宝实现类，未支持平台会打印警告「插件暂时不支持 xx 平台」并返回。

六、version 与 desc 的来源与优先级

version（上传版本号）与desc（上传描述）无需在每个命令里重复传递，插件会按以下优先级取值（见 src/BaseCi.ts）：

1. 插件配置对象中的version/desc字段；
2. 否则读取项目package.json下taroConfig字段中的version/desc；
3. desc仍未配置时，默认生成CI构建自动构建于${当前时间}。

因此上述示例中，package.json里统一维护taroConfig即可：

{ "taroConfig": { "version": "1.0.0", "desc": "上传描述" } }

七、Hooks 扩展：预览/上传完成后回调通知

7.1 触发时机与事件

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

钩子由基类的triggerPreviewHooks/triggerUploadHooks通过ctx.applyPlugins触发（见 src/BaseCi.ts），事件名常量定义在 src/hooks.ts。钩子数据中会自动带上当前的version、desc、projectPath。需要留意：当动作失败（success: false）时，插件会调用process.exit(1)终止进程，这可以保证 CI 流水线在预览/上传失败时立即失败，避免误报成功。

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

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

7.2 自定义插件接收事件

你可以写一个自定义 Taro 插件，通过ctx.register注册上述两个事件，实现「预览/上传成功后自动发送钉钉或飞书消息」等扩展能力：

// 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')) }

八、各平台功能支持情况对比

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

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

二维码的生成与读取机制：插件使用 src/utils/qrcode.ts 中的工具函数统一处理二维码——readQrcodeImageContent用axios+Jimp+jsQR读取（含网络图片）二维码图片中的文本内容；printQrcode2Terminal用qrcode库把内容直接打印成终端 ASCII 二维码；generateQrcodeImageFile把内容生成为 PNG 图片文件。例如微信平台（WeappCI.ts）预览二维码保存在projectPath/preview.jpg，体验版二维码按https://open.weixin.qq.com/sns/getexpappinfo?appid=xxx#wechat-redirect规则生成并保存在projectPath/upload.png；支付宝平台（AlipayCI.ts）预览二维码保存在projectPath/preview.png，体验版二维码保存在projectPath/upload.png。

九、插件完整配置 API

9.1 顶层插件配置（CIOptions）

9.2 （企业）微信小程序 CI 配置

编译设置选项说明（setting）

实现细节（WeappCI.ts）：init()阶段会校验weapp配置存在、动态加载miniprogram-ci、拼接并校验私钥路径；privateKeyPath支持绝对路径，相对路径会基于项目根目录解析，路径不存在则直接抛错终止上传；devToolsInstallPath默认取 macOS 的/Applications/wechatwebdevtools.app或 Windows 的C:\Program Files (x86)\Tencent\微信web开发者工具。open()动作会进一步检查开发者工具是否开启「服务端口」（通过用户目录下 IDE 的.ide-status文件判断），未开启时会提示前往「设置 → 安全设置」打开服务端口。上传成功后还会根据subPackageInfo打印主包/整包体积信息。

9.3 头条（字节/抖音）小程序 CI 配置

从源码 TTCI.ts 看，预览/上传前会先调用tt-ide-cli的loginByEmail完成邮箱登录（dontSaveCookie: false会保存登录 Cookie）；上传时支持setting.skipDomainCheck跳过域名检查，并默认needUploadSourcemap: true上传 SourceMap。

9.4 支付宝小程序 CI 配置

终端类型值及其含义（clientType）：

alipay: 支付宝 ampe：AMPE amap：高德 genie：天猫精灵 alios：ALIOS uc：UC quark：夸克 koubei：口碑 alipayiot：IoT cainiao：菜鸟 alihealth：阿里健康 health: 阿里医院

实现细节（AlipayCI.ts）：privateKey与privateKeyPath二选一，若只配置了privateKeyPath会读取该文件内容作为私钥，并写入minidev的默认配置；上传时会先查询最新已上传版本号，若当前version不高于线上最新版本会报错终止（SDK 要求版本号必须递增），同时默认把上一个版本作为deleteVersion删除，以规避支付宝平台上体验版本数量上限问题。

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

taro集成的钉钉 CI 使用了钉钉官方dingtalk-design-cli中的dingtalk-miniapp-opensdk包，查阅源码封装而成。另外，类型定义（src/BaseCi.ts）还提供了projectType字段（默认dingtalk-biz企业内部应用），可指定dingtalk-personal（第三方个人应用）、dingtalk-biz-isv（第三方企业应用）、dingtalk-biz-custom（企业定制应用）、dingtalk-biz-worktab-plugin（工作台组件）等应用类型。

9.6 百度小程序 CI 配置

类型定义中百度配置还包含可选的devToolsInstallPath（小程序开发者工具安装路径），见 src/BaseCi.ts。

9.7 京东小程序 CI 配置

十、完整 TS 接口描述

插件通过 src/BaseCi.ts 导出完整的 TypeScript 类型声明，接入项目后在编辑器中可获得完整的类型提示：

export interface CIOptions { /** 发布版本号，默认取 package.json 文件的 taroConfig.version 字段 */ version?: string /** 版本发布描述，默认取 package.json 文件的 taroConfig.desc 字段 */ desc?: string /** 目标项目目录，对所有小程序生效（不传默认取 outputRoot 字段） */ projectPath?: string /** 微信小程序 CI 配置 */ weapp?: WeappConfig /** 头条小程序配置 */ tt?: TTConfig /** 支付宝系列小程序配置 */ alipay?: AlipayConfig /** 钉钉小程序配置 */ dd?: DingtalkConfig /** 百度小程序配置 */ swan?: SwanConfig /** 京东小程序配置 */ 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' /** 口碑 */ | 'alipayiot'/** IoT */ | '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 /** 上传时想要删除的一个版本 */ deleteVersion?: string } 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[] }

十一、CI/CD 流水线中的典型用法

将上述能力组合进流水线即可形成完整的「构建 → 上传 → 通知」链路，例如：

1. 本地/流水线构建：执行taro build --type weapp产出dist目录；
2. 上传体验版：执行npx taro upload --type weapp（或taro build --type weapp --upload），版本号与描述由taroConfig统一提供；
3. 结果通知：通过自定义插件监听onUploadComplete/onPreviewComplete事件，把data（平台、二维码本地路径、二维码内容、版本号、描述、项目路径）与success状态推送到钉钉/飞书/企微群机器人；
4. 失败即中断：预览/上传失败时插件会process.exit(1)，确保流水线任务标记为失败。

结语

@tarojs/plugin-mini-ci把小程序多平台「打开工具、预览、上传体验版」这些高频重复操作收敛为 3 个 CLI 选项与 3 个独立命令，配合可选的 Hooks 事件，足以覆盖日常开发与 CI 流水线的核心诉求。配置上只需在 config/index.js 声明平台参数，并在package.json的taroConfig中维护版本号与描述；实现层面每个平台都有独立的 CI 类（src/WeappCI.ts、src/TTCI.ts、src/AlipayCI.ts 等）与统一的二维码工具（src/utils/qrcode.ts），需要排查问题时可直接深入对应源码。

【免费下载链接】taro开放式跨端跨框架解决方案，支持使用 React/Vue/Nerv 等框架来开发微信/京东/百度/支付宝/字节跳动/ QQ 小程序/H5/React Native 等应用。 https://taro.zone/项目地址: https://gitcode.com/NervJS/taro