npm package: @ifanrx/minci
Description: 用于小程序项目开发预览、代码上传。
Author: ifanrX Team
Latest version: 0.0.2

# minci

用于小程序项目开发预览、代码上传。

## 使用必读

minci 内部会有知晓云数据表的读写操作，是需要授权认证的，在使用之前，你现在可能需要：

1. 找负责人添加 minci 的知晓云应用的权限（已有跳过）。
2. 执行一次 `npx minci login <client-secret>` 以登录生成 Token（已登录跳过）。若后续 Token 失效，重新登录即可。

团队约定：

minci 的上传和预览，默认使用「ci 机器人 1」（相当于开发工具登录的微信帐号），应将该机器人上传的版本指定为体验版，提交审核也应该使用该版本，避免出现 A 同学提交 ci 机器人 2 版本、B 同学提交 ci 机器人 3 版本...的情况。

如有特殊情况，又不想覆盖 ci 机器人 1 的版本，可以使用 `--robot` 参数指定为其他机器人，取值 2 ~ 30。

## 安装

```shell
$ pnpm add @ifanrx/minci -D
```

目前提供了以下命令：

- `minci preview`
- `minci upload`
- `minci login`
- `minci set`
- `minci info`

更多细节请看 `minci -h` 或 `minci <subcommand> -h`。

```shell
$ npx minci -h
Usage: minci [options] [command]

用于小程序项目开发预览、代码上传。

Options:
  -v, --version          显示版本信息
  -h, --help             显示帮助信息

Commands:
  preview [options]      项目预览。
  upload [options]       项目打包，并上传代码至小程序后台。
  login <client-secret>  登录知晓云 minci 应用。请注意，它不是登录当前小程序所属知晓云应用。
  set                    配置当前小程序的 minci 信息，包括小程序名称、代码上传密钥、WebHook。
  info                   显示当前小程序的 minci 信息。
  start [options]        项目开发。仅在原生小程序开发模式下可用。
  build [options]        项目打包。仅在原生小程序开发模式下可用。
  help [command]         显示帮助信息
```

## uni-app 项目接入

在小程序根目录下创建 `minci.config.js` 配置文件（支持 `.cjs`），如下：

```js
// minci.config.js
module.exports = {
  outputRoot: 'dist/dev/mp-weixin', // 指定编译产物目录，根据项目实际情况配置
}
```

TIPS：

1. 我们知道 uni-app 项目开发、打包的默认产物目录分别是 `dist/dev/mp-weixin`、`dist/build/mp-weixin`。但在团队内部的 uni-app 项目，`pnpm build` 之后会将 `dist/build/mp-weixin` 拷贝到 `dist/dev/mp-weixin` 目录（[详见](https://cloud-minapp-41176.myxiaoapp.com/docs/guide/manual-install.html#%E9%BB%98%E8%AE%A4%E9%85%8D%E7%BD%AE%E5%86%85%E5%AE%B9)），因此给出的配置示例可以兼容开发、打包两种场景。如果没有类似的拷贝操作的项目，则按实际情况配置 `outputRoot`。

在小程序的 `package.json` 中按需配置添加预览和上传 Scripts，比如：

```json
{
  "name": "miniapp",
  "scripts": {
    "dev": "uni -p mp-weixin -- --BAAS_DEV",
    "dev:prod": "uni -p mp-weixin",
    "dev:qa": "uni -p mp-weixin -- --BAAS_QA",
    "build": "uni build -p mp-weixin",

    "preview": "pnpm build:dev && minci preview",
    "preview:prod": "pnpm build && minci preview",
    "preview:qa": "pnpm build:qa && minci preview",
    "upload": "pnpm build && minci upload"
  }
}
```

TIPS:

1. 示例中上传和预览使用的是 `pnpm build`，而不是 `pnpm dev`。原因是后者会一直开着 watch 模式，进程不会关掉，导致无法执行后面的上传或预览命令。
2. 前面 `minci.config.js` 文件 `outputRoot` 配置 `dist/dev/mp-weixin`，开发时可以直接使用 `npx minci preview` 进行预览，不用停掉 `pnpm dev`。
3. `minci upload` 的 `--env` 参数，默认值是 `production`，它对 uni-app 项目的代码不起任何作用，只用于推送企微群组消息，用来表明当前上传的版本是哪个环境。其中 `production`、`development`、`qa` 分别表示使用了知晓云的生产、测试和 QA 环境。

若项目**首次**接入 minci，必须先执行 `npx minci set` 完成相关配置才能进行预览或上传，配置包括小程序名称、小程序代码上传密钥、企业微信群组机器人 WebHook。若已接入，则跳过。若后续需要修改密钥、机器人，也使用该命令进行更新。

TIPS:

1. 小程序代码上传密钥在「微信公众平台 - 登录对应小程序 - 开发 - 开发设置 - 小程序代码上传」处生成。
2. **请注意「小程序代码上传密钥」和「AppSecret 小程序密钥」是两个不同的东西，它们都在微信后台的同一页面，还上下挨着，千万别弄错了！！！**
3. 由于微信公众后台默认开启 IP 白名单选项（[详见](https://developers.weixin.qq.com/miniprogram/dev/devtools/ci.html)），只有白名单内的 IP 地址才能成功调用上传接口，由于团队成员较多，且 IP 地址可能会随时发生变化，所以基本上是要关闭「IP 白名单」选项的。

## 小程序版本说明

> 小程序上传版本号由 minci 内部维护，使用时无需手动设置。

由于微信未提供获取小程序线上版本号的能力，使得无法很好地维护上传版本号，加上语义化版本对小程序版本意义不大，现使用 minci 上传代码版本号将使用 [ChronVer](https://chronver.org/) 来替代 [SemVer](https://semver.org/)，形式为 `Year.Month.Day.Change`，其中 `Change` 可选。

假设某天首次上传了一个版本为 `2022.07.05`，当天晚些时候又上传了新版本，版本将变为 `2022.07.05.1`，即同一天提交的版本 `Change + 1`。次日第一次提交将变为 `2022.07.06`，以此类推。

## 原生小程序开发项目接入

对于原生小程序项目，还提供了开发和打包命令：

- `minci start`
- `minci build`

在小程序根目录下创建 `minci.config.js` 配置文件，相比 uni-app 项目，配置项会多一些，比如：

```js
module.exports = {
  depsTool: 'pnpm', // 指定依赖安装工具 pnpm/yarn/npm（小程序 NPM 构建时安装依赖用）
  sourceRoot: 'src', // 指定开发源码目录（相对路径，相当于小程序根目录，下同）
  outputRoot: 'dist', // 指定编译产物目录
  mode: 'native', // 指定项目开发模式
}
```

推荐添加 `tsconfig.json` 文件，并配置路径别名（可选）

```json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}
```

若有配置路径别名，源码中可以这样用：

```js
// 之前
import constants from '../../../../constants/index'

// 现在
import constants from '@/constants'
```

在构建时，minci 会自动识别路径别名，然后编译成小程序可识别的真实路径。

对于原生小程序项目里，`--env` 参数还有其他用处，比如：

```js
export const isDev = process.env.NODE_ENV === 'development'
export const isQa = process.env.NODE_ENV === 'qa'
```

在构建时，minci 会将 `process.env.NODE_ENV` 替换成 `--env` 参数传入的值（是字符串替换，所以不支持 `process.env['NODE_ENV']` 等写法）。比如执行 `minci start --env qa` 会被编译为：

```js
export const isDev = 'qa' === 'development'
export const isQa = 'qa' === 'qa'
```

其中 `--env` 默认值如下：

- `minci start`、`minci preview` 为 `development`，即测试环境
- `minci build`、`minci upload` 为 `production`，即生产环境

> 再次强调，`--env` 对 uni-app 项目的代码不起任何作用，只用于 `minci upload` 附带的企微群组消息推送，用来表明当前上传的版本是哪个环境。