English | 简体中文

@tcsas-team/tcsas-miniprogram-ci

@tcsas-team/tcsas-miniprogram-ci 是一个用于自动化 TCSAS 小程序上传、预览和依赖构建的 Node.js 工具。它既可以作为命令行工具（CLI）在终端直接使用，也可以作为 NPM 包在您的项目中通过代码调用。

✨ 功能特性

• 上传小程序: 将代码上传，对应小程序开发者工具的上传。
• 预览小程序: 生成预览二维码，方便真机调试，对应小程序开发者工具的预览。
• NPM 构建: 自动构建小程序项目中的 npm 依赖，对应小程序开发者工具的: 菜单-工具-构建npm。
• 详细进度: 提供 onProgressUpdate 回调，实时追踪任务状态。

📦 安装

全局安装 (用于命令行 CLI)

如果您希望在任何地方直接使用 tcsas-miniprogram-ci 命令，请进行全局安装：

npm install -g @tcsas-team/tcsas-miniprogram-ci

本地安装 (用于项目内调用)

如果您希望在自己的 Node.js 项目中通过 require 使用，请进行本地安装：

npm install @tcsas-team/tcsas-miniprogram-ci

🔑 前置准备：获取密钥文件

在使用本工具前，您必须先从 TCSAS 控制台获取专用的 CI/CD 密钥文件。该过程涉及两个关键步骤：

第一步：平台管理员创建并授权密钥对

1. 使用 TCSAS 平台管理员 账号登录 TCSAS 控制台。
2. 访问 “平台管理-OpenAPI管理” 菜单，并切换到 “密钥管理” Tab 页面。
3. 点击“新建密钥对”，创建一个用于 CI/CD 的密钥，注意不要开启“密钥轮换机制”。
4. 在创建过程中，必须勾选以下 4 个 OpenAPI 权限：
   • FileUpload
   • CreateMNPVersion
   • DescribeMNPVersion
   • CreateMNPSecretKey
5. 生成密钥后，下载并妥善保管平台层级的 .csv 密钥文件。

第二步：小程序团队管理员上传并下载最终密钥

1. 使用 小程序团队管理员 账号登录 TCSAS 控制台。
2. 访问 “团队管理-CI/CD” 菜单。
3. 将第一步中下载的平台层级密钥文件进行上传。
4. 上传成功后，系统会生成一个与团队小程序绑定的新密钥，并自动下载 .key 文件。

✅ 最终，您在 privateKeyPath 参数中使用的就是这第二步下载的密钥文件。

🚀 使用指南

该工具支持两种核心使用方式：作为 NPM 包 在代码中调用，或作为 CLI 在命令行中执行。

1. 作为 NPM 包使用

在您的 Node.js 脚本中，首先需要引入包并实例化一个 Project 对象。

a. 初始化 Project

所有操作都需要一个 Project 实例，它包含了小程序的必要配置信息。

const ci = require('@tcsas-team/tcsas-miniprogram-ci');

// 注意： new ci.Project 调用时，请确保项目代码已经是完整的，避免编译过程出现找不到文件的报错。
const project = new ci.Project({
  appid: 'wxsomeappid',
  type: 'miniProgram',
  projectPath: 'your/project/path',
  privateKeyPath: 'your/path/to/privatekey',
});

Project 构造函数参数:

| 参数 | 类型 | 是否必填 | 描述 | | ---------------- | -------- | -------- | -------------------------------------------------------------------- | | appid | string | 是 | 小程序的 AppID。 | | projectPath | string | 是 | 小程序项目的根目录路径。 | | privateKeyPath | string | 否 | 代码上传密钥文件的路径。与 privateKey 二选一。 | | privateKey | string | 否 | 代码上传密钥的文本内容。与 privateKeyPath 二选一。 | | type | string | 否 | 项目类型，可选值为 'miniProgram' (默认) 或 'miniGame'。 |

b. 上传代码 ci.upload()

将项目代码上传，并可以设置为体验版。

(async () => {
  const uploadResult = await ci.upload({
    project,
    version: '1.0.1',
    desc: 'hello',
    onProgressUpdate: (info) => console.log(info),
  });
  console.log(uploadResult);
})();

upload 函数参数:

| 参数 | 类型 | 是否必填 | 描述 | | ------------------ | ---------- | -------- | -------------------------------------------------------------------- | | project | Project | 是 | 通过 new ci.Project() 创建的项目实例。 | | version | string | 是 | 本次上传的版本号，例如 '1.0.1'。 | | desc | string | 否 | 版本描述。 | | onProgressUpdate | Function | 否 | 进度更新回调函数，详见 进度更新回调。 |

返回值

函数返回一个 Promise，成功后 resolve 一个包含小程序包信息的对象：

| 属性 | 类型 | 描述 | | ---------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | subPackageInfo | Array<Object> | 小程序包信息。数组中每个对象包含：name (string): 代码包名称。(为__FULL__ 时表示整个小程序包，为 __APP__ 时表示小程序主包，其他情况都表示分包)。size (number): 代码包大小，单位 B。 |

c. 预览代码 ci.preview()

生成一个预览二维码，用于真机调试。

(async () => {
  const previewResult = await ci.preview({
    project,
    desc: 'hello',
    onProgressUpdate: console.log,
    qrcodeFormat: 'image',
    qrcodeOutputDest: './preview-qrcode.jpg',
    pagePath: 'pages/index/index',
    searchQuery: 'from=test',
  });
  console.log(previewResult);
})();

preview 函数参数:

| 参数 | 类型 | 是否必填 | 描述 | | ------------------ | ---------- | -------------- | ------------------------------------------------------------------------------------------------- | | project | Project | 是 | 通过 new ci.Project() 创建的项目实例。 | | desc | string | 否 | 预览版本的描述。 | | onProgressUpdate | Function | 否 | 进度更新回调函数。 | | qrcodeFormat | string | 否 | 返回二维码的格式，可选值：'terminal' (默认), 'image', 'base64'。 | | qrcodeOutputDest | string | 是 | 二维码文件的保存路径。qrcodeFormat 为 image 或 base64 时必填 | | pagePath | string | 否 | 指定预览的页面路径。 | | searchQuery | string | 否 | 指定预览页面的启动参数，例如 'a=1&b=2'。 | | bigPackageSizeSupport | boolean | 否 | 预览时是否启用分包大小优化，开启后分包/主包大小上限提升至 4M（小游戏为 8M）。 |

返回值

函数返回一个 Promise，成功后 resolve 一个包含预览信息的对象：

| 属性 | 类型 | 描述 | | ---------------- | --------------------- | -------------------------------------------------------------------- | | subPackageInfo | Array<Object> | 代码包大小信息，结构同 upload 函数的返回值。 | | expireTime | number | 二维码过期时间的时间戳。 |

d. NPM 构建

ci.packNpm(project, options): 在项目配置的 miniprogramRoot 目录内执行 npm 构建。

await ci.packNpm(project, {
  reporter: (infos) => { console.log(infos) }
});

ci.packNpmManually(options): 手动指定 package.json 路径和输出目录来执行 npm 构建。

示例：自定义 node_modules 位置的构建

在某些场景下，需要被构建的 node_modules 可能位于小程序项目之外。packNpmManually 就是为了支持这种需求。例如，有如下项目结构：

.
├── lib                # 存放 node_modules 和 package.json 的目录
│   ├── node_modules
│   └── package.json
└── miniprogram-project # 小程序项目目录
    └── miniprogram      # 希望最终把 miniprogram_npm 构建在 miniprogram/ 目录之下

您可以使用以下代码来完成构建和移动：

await ci.packNpmManually({
  packageJsonPath: './lib/package.json',
  miniprogramNpmDistDir: './miniprogram-project/miniprogram/',
});

执行完毕后，最终的项目结构会变成：

.
├── lib
│   ├── node_modules
│   └── package.json
└── miniprogram-project
    ├── miniprogram
    │   ├── app.js
    │   ├── app.json
    │   ├── app.wxss
    │   ├── miniprogram_npm # <--- 这就是构建出来的由 lib/node_modules 里 miniprogram_npm 了
    │   ├── pages
    │   └── sitemap.json
    └── project.config.json

packNpmManually 函数参数:

| 参数 | 类型 | 是否必填 | 描述 | | ----------------------- | -------- | -------- | ---------------------------------------------------------| | packageJsonPath | string | 是 | 希望被构建的 node_modules 对应的 package.json 的路径 | |miniprogramNpmDistDir|string| **是** | 构建产物miniprogram_npm` 的最终输出目录。 |

2. 作为 CLI 使用

在终端中，使用 tcsas-miniprogram-ci 命令加上对应的子命令（upload 或 preview）来执行操作。

a. upload 命令

tcsas-miniprogram-ci upload \
  --project-path ./demo-proj/ \
  --private-key-path ./private.key \
  --appid YOUR_APPID \
  --upload-version 1.0.1 \
  --upload-desc "hello"

upload 命令参数:

| 参数 | 别名 | 是否必填 | 描述 | | -------------------- | ---- | -------- | ---------------------- | | --project-path | --pp | 是 | 小程序项目路径。 | | --private-key-path | --pkp| 是 | 密钥文件路径。 | | --appid | | 是 | 小程序 AppID。 | | --upload-version | --uv | 是 | 上传的版本号。 | | --upload-desc | --ud | 否 | 版本描述。 |

b. preview 命令

tcsas-miniprogram-ci preview \
  --project-path ./demo-proj/ \
  --private-key-path ./private.key \
  --appid YOUR_APPID \
  --qrcode-format image \
  --qrcode-output-dest '/tmp/qrcode.jpg'

preview 命令参数:

| 参数 | 别名 | 是否必填 | 描述 | | ---------------------------- | ---- | -------- | ------------------------------------------ | | --project-path | --pp | 是 | 小程序项目路径。 | | --private-key-path | --pkp| 是 | 密钥文件路径。 | | --appid | | 是 | 小程序 AppID。 | | --qrcode-format | | 否 | 二维码格式，可选 'terminal', 'image'。 | | --qrcode-output-dest | | 否 | 二维码文件输出路径。 |

c. pack-npm 和 pack-npm-manually 命令

# 在项目内构建
tcsas-miniprogram-ci pack-npm --project-path ./YOUR_PROJECT/

# 手动构建
tcsas-miniprogram-ci pack-npm-manually \
  --pack-npm-manually-package-json-path PACKAGE_JSON_PATH \
  --pack-npm-manually-miniprogram-npm-dist-dir DIST_PATH

⚙️ 进度更新回调 (onProgressUpdate)

onProgressUpdate 是一个函数，用于接收工具在执行过程中的各个阶段性状态。该函数接收一个对象作为参数，格式如下：

{ message: string, status: 'doing' | 'done' }

• message: 当前状态的描述信息。
• status:
  • 'doing': 当前任务正在处理中。
  • 'done': 当前任务已成功完成。

注意: 当任务失败时，会直接抛出异常 (throw error)，此时不会调用 onProgressUpdate。

使用示例:

const onProgressUpdate = (info) => {
   console.log(info);
};

await ci.upload({
  project,
  version: '1.0.1',
  onProgressUpdate,
});

📄 License

MIT