English | 简体中文

@tcsas-team/tcsas-miniprogram-ci

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

✨ 功能特性

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

📦 安装

$3

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

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

$3

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

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

---

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

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

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

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

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

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

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

---

🚀 使用指南

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

$3

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

#### a. 初始化 Project

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

`javascript
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()

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

`javascript
(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