uz-miniprogram-ci

一键发布微信和支付宝小程序的命令行工具。

适用场景

Git CI/CD、Jenkins等自动化流程场景，本工具可简化上传代码发布的流程。 适用流程如下：

1. 项目开发
2. build打包项目（原生开发可忽略）
3. 使用uz release命令上传发布体验版小程序
4. 将体验版二维码通知到钉钉群或飞书群等
5. 人工送审小程序完成上架（涉及人员管理权限等问题，建议人工处理）

安装

npm install -g uz-miniprogram-ci

使用方法

配置 .env.release 文件

在项目根目录下创建 .env.release 文件，用于配置版本号和版本描述：

RELEASE_VERSION=1.0.0
RELEASE_DESC=常规更新

命令行使用

# 发布微信小程序
uz release weixin <appid> <密钥文件路径> <发布代码的路径>

# 发布支付宝小程序
uz release alipay <appid> <config.json路径> <发布代码的路径>

例如：

# 发布微信小程序
uz release weixin wx1234567890 ./path/to/private.key ./path/to/miniprogram

# 发布支付宝小程序
uz release alipay 2021000000000000 ./path/to/config.json ./path/to/miniprogram

版本号和版本描述会从项目根目录下的 .env.release 文件读取。

功能特点

1. 自动读取配置：从 .env.release 文件读取版本号和版本描述，开发者自行管理版本及版本描述
2. 支持多平台：支持微信小程序和支付宝小程序的发布
3. 智能配置继承：自动使用项目中已有的编译配置
4. 预览二维码生成：微信和支付宝小程序发布成功后，自动生成预览二维码并保存在代码目录下
5. 自动完成退出：发布操作完成后自动退出命令行，无需手动中断
6. 版本稳定可靠：使用锁定版本的依赖工具，确保发布流程稳定可靠
7. 平台特性支持：为不同平台提供最适合的发布流程和配置方式

预览二维码

工具发布完成后自动保存预览二维码，您可以将二维码接入钉钉群或者微信企业号将二维码发送到群内或者其他方式共享给项目成员。

微信小程序发布成功后，会自动生成一个预览二维码，并保存在代码路径下的 preview_qrcode.jpg 文件中。预览页面默认使用 app.json 中配置的第一个页面。

支付宝小程序发布成功后，会自动从预览命令输出提取二维码URL，下载保存到代码路径下的 preview_qrcode.jpg 文件。您可以使用支付宝扫描此二维码直接预览小程序。

自动退出

发布操作完成后（无论成功还是失败），工具会自动退出命令行。这对于在自动化流程或 CI/CD 环境中使用特别有用，无需手动中断或额外处理。

配置项说明

微信小程序

对于微信小程序，工具会使用 miniprogram-ci 2.0.10 版本的 useProjectConfig 特性，自动使用项目中 project.config.json 文件的配置。这意味着您在微信开发者工具中的设置会自动应用到上传过程中，无需额外配置。

微信小程序使用密钥文件：您需要提供从微信小程序后台下载的私钥文件(.key)作为参数。

项目中 project.config.json 的设置会被自动识别，包括但不限于：

• ES6 转 ES5
• 代码压缩选项
• 代码保护
• 样式自动补全
• Worklet 编译
• SWC 编译模式 (2.0.0 版本新增)

您只需确保您的 project.config.json 文件中包含了所需的编译设置，工具会自动读取并应用这些设置。

支付宝小程序

对于支付宝小程序，工具使用指定版本(2.2.5)的 minidev 工具进行构建和上传。为了确保发布流程的稳定性和可靠性，我们锁定了minidev的版本，这样可以避免因工具更新带来的潜在兼容性问题。

支付宝小程序必须使用config.json配置文件：根据支付宝minidev工具的要求，必须使用JSON格式的配置文件来提供授权信息，不支持直接使用私钥文件。

工具会完成以下操作：

1. 检查并确保安装了2.2.5版本的minidev
2. 编译小程序代码
3. 上传小程序包到支付宝开发者平台
4. 自动生成体验版预览二维码

支持的config.json文件格式有多种：

1. 支付宝开发者工具格式：包含tools和currently字段
2. 自定义格式：直接在根级别包含privateKey和可选的toolId
3. 嵌套格式：认证信息位于alipay.authentication路径下

config.json文件一般位于：

• Windows: %APPDATA%\minidev\config.json
• macOS: ~/Library/Application Support/minidev/config.json

但您也可以自定义config.json文件，只要它遵循以下格式之一：

// 格式：嵌套在alipay.authentication路径下
{
  "alipay": {
    "authentication": {
      "toolId": "工具ID",
      "privateKey": "私钥内容"
    }
  }
}

作为模块使用

也可以在代码中引入并使用：

const { releaseWeixin, releaseAlipay, readPublishEnv } = require('uz-miniprogram-ci');

// 读取发布环境变量
const env = readPublishEnv();
const { version, desc } = env;

// 发布微信小程序
releaseWeixin('wx1234567890', './path/to/private.key', './path/to/miniprogram', version, desc)
  .then(() => console.log('发布成功'))
  .catch(err => console.error('发布失败', err));

// 发布支付宝小程序
releaseAlipay('2021000000000000', './path/to/config.json', './path/to/miniprogram', version, desc)
  .then(() => console.log('发布成功'))
  .catch(err => console.error('发布失败', err));

注意事项

1. 使用前确保你有相应小程序的开发权限和有效的授权文件且Node版本需要>=16.1.0
2. 确保在项目根目录下创建了 .env.release 文件，并定义了 RELEASE_VERSION 和 RELEASE_DESC 字段。
3. 对于微信小程序，确保代码路径下有 project.config.json 文件，工具会自动使用其中的配置。
4. 对于支付宝小程序，确保代码路径下有 mini.project.json 文件，并提供有效的config.json文件。
5. 工具依赖的 miniprogram-ci 库版本为 2.0.10。
6. 预览二维码生成需要项目中包含 app.json 文件，且其中定义了 pages 数组。
7. 支付宝小程序发布使用的minidev工具版本被锁定为2.2.5，确保发布流程稳定可靠。

依赖

• Node >= 16.1.0
• 微信小程序发布依赖 miniprogram-ci 2.0.10
• 支付宝小程序发布依赖 minidev 2.2.5

故障排除

微信小程序发布问题

Error: common.js: undefined

这个错误通常与 miniprogram-ci 库有关，可能的解决方案：

1. 检查密钥文件：

   • 确保密钥文件格式正确，是从微信小程序后台下载的有效私钥
   • 密钥文件不要有多余的换行或空格
   • 验证 AppID 与密钥是否匹配

2. 检查项目文件：

   • 确保 project.config.json 存在且格式正确
   • 检查 miniprogramRoot 路径设置是否正确

3. 确认 Node.js 版本兼容性：

   • Node >= 16.1.0

4. 权限问题：

   • 确保有小程序的上传权限
   • 检查小程序开发者身份是否过期

401 Unauthorized

• 检查 AppID 和密钥是否正确
• 确认当前账号是否有发布权限

无法生成预览二维码

• 检查 app.json 文件是否存在且格式正确
• 确保 app.json 中包含有效的 pages 数组
• 确认上传代码过程已成功完成

支付宝小程序发布问题

minidev 命令未找到

确保全局安装了minidev 2.2.5版本：

npm install -g [email protected]

上传错误

• 确保已正确设置支付宝小程序的开发者权限
• 检查 mini.project.json 文件是否正确配置
• 确保使用的是minidev 2.2.5版本
• 必须提供有效的config.json授权文件，支付宝不支持直接使用私钥文件
• minidev 2.2.5版本支持的主要参数:
  • -a, --app-id <appId> 指定小程序应用id（必填）
  • -v, --version [version] 指定上传包版本（可选）
  • --version-description <versionDescription> 指定版本描述（可选）
  • -e, --experience 自动设置为体验版本（可选）
  • --identity-key-path <identityKeyPath> 指定身份密钥路径（可选）

常见错误与解决方案

• 使用 minidev upload --help 命令查看当前安装的minidev版本支持的参数列表

支付宝config.json相关问题

• 确保config.json文件格式正确
• 如果直接使用支付宝开发者工具的config.json，确保已先在开发者工具中登录并配置好密钥
• 可以手动编辑config.json文件，添加privateKey和toolId字段
• 支持多种格式的config.json，包括直接模式、开发者工具模式和alipay.authentication嵌套模式
• 如需生成密钥和配置指导，请参考支付宝官方文档

预览二维码生成失败

• 确保上传步骤已成功完成
• 检查appid和config.json文件权限是否正确
• 查看预览命令输出的详细错误信息
• 如果预览二维码URL下载失败，工具会在控制台输出URL，您可以手动复制并访问
• 如果无法从输出中提取二维码URL，您可以登录支付宝开放平台，在小程序详情页面查看体验版二维码
• 小程序开发版、体验版二维码通常可在小程序管理后台的"版本管理"页面获取

许可证

MIT