# @shencom/oss-upload

> 使用说明

## 介绍

`oss-upload` 用于日常部署前端代码自动化脚本;

基于 `rollup/typescript` 构建，`CommonJS` 和 `ESModule`;

## 安装

```sh
yarn add -D @shencom/oss-upload
# or
yarn add -D git+https://gitlab.shencom.cn/web/tools/oss-upload.git#master
```

## 使用

> **注意:** 需要提前配置秘钥

### 配置秘钥

可以使用以下两种方式配置秘钥

1. 可以使用 `@shencom/cli` 创建秘钥 <code style="color:#ed5a65">(推荐)</code>

```sh
# 全局配置:
pnpm add @shencom/cli && pnpm sc oss config

# 项目配置:
pnpm add @shencom/cli && pnpm sc oss config -p
```

2. 在当前项目根目录创建 `.env.oss.local` 文件，并配置如下内容:

```
accessKeySecret=xxx
accessKeyId=xxx
```

### 初始化

- 类型

```ts
new OSS(ops: OssOptions): OSS
```

- 示例

```ts
import { OSS } from '@shencom/oss-upload';

const CLIENT = new OSS({
  ignore: ['**/assets/**'], // 过滤文件同 glob.ignore 规则
  ossPath: `xxx`, // oss基础路径。如: plugins/test/scloud/xxx
});
```

- `OssOptions` 说明

| 参数           | 说明                                    | 类型       | 可选项 | 默认值       |
| -------------- | --------------------------------------- | ---------- | ------ | ------------ |
| `ossPath`      | oss 基础路径                            | `string`   | 必填   | -            |
| `bucket`       | bucket 名，一般不需要填写               | `string`   | -      | `scplugins`  |
| `ignore`       | 过滤上传、删除文件，同 glob.ignore 规则 | `string[]` | -      | -            |
| `deleteIgnore` | 过滤删除 oss 文件，合并`ignore`         | `string[]` | -      | -            |
| `uploadIgnore` | 过滤上传 oss 文件，合并`ignore`         | `string[]` | -      | -            |
| `timeout`      | 超时时间                                | `number`   | -      | `1000*60*10` |

### 方法

**list**

- 说明: 获取 oss 文件列表
- 类型: `OSS.list(ossPaths: string[] | string, returnType?: 'file' | 'dir' | 'all', options?: AliOSS.ListV2ObjectsQuery): Promise<AliOSS.ObjectMeta|string[]|Pick<AliOSS.ListObjectResult, 'objects' | 'prefixes'>[]>`
- 参数:
  - `ossPaths`: oss 路径
  - `returnType?`: 返回类型，默认: `all`
  - `options?`: oss 配置，当 `returnType=all` 时生效
- 示例:
  ```ts
  const list = await CLIENT.list(ossPaths, returnType, options);
  ```

**head**

- 说明: 批量获取 oss 文件的 md5
- 类型: `OSS.head(ossFilePaths: string[]): Promise<FileData[]>`
- 参数:
  - `ossFilePaths`: oss 文件路径
- 示例:
  ```ts
  const objects = await CLIENT.head(ossFilePaths);
  ```

**put**

- 说明: 删除 oss 文件
- 类型: `OSS.delete(ossPaths: string[]): void`
- 参数:
  - `ossPaths`: oss 文件路径
- 示例:
  ```ts
  await CLIENT.delete(paths);
  ```

**put**

- 说明: 上传文件
- 类型: `OSS.put(paths: OssUploadItem[]): void`
- 参数:
  - `paths`: 上传路径对象
- 示例:
  ```ts
  await CLIENT.put(paths);
  ```

**clearVersionDir**

- 说明: 清除版本号文件夹
- 类型: `OSS.clearVersionDir(paths: string[], limit?: number): void`
- 参数:
  - `paths`: 文件路径
  - `limit?`: 保留版本号目录个数，默认值: `10`
- 示例:
  ```ts
  await CLIENT.clearVersionDir(paths, limit);
  ```

**upload**

- 说明: 代码上传
- 类型: `OSS.upload(ops: UploadOptions): void`
- 参数:
  - `ops`: 上传配置
- 示例: 参考下面说明

#### upload 使用说明

```ts
CLIENT.upload(ops: UploadOptions): Promise<void>
```

```ts
CLIENT.upload({
  /**
   * 构建后的目录
   * 如:
   *   dirPath: 'xxx',
   *   dirPath: 'xxx/xxx',
   */
  dirPath: 'xxx',

  /** 是否开启本地文件和oss文件进行对比 */
  // diff: false,

  /** 开启debug，开启后不进行上传和删除操作 */
  // debug: true,

  /** 是否开启清除版本号目录，默认: false */
  // isClearVersion: false,

  /** 保留版本号目录个数，默认: 10 */
  // versionLimit: 10,

  /** 当前版本号 */
  // version: 1.0.0;

  /** 处理获取本地文件列表钩子 */
  // localFileHook: (data) => data,

  /** 处理oss路径列表钩子 */
  // ossPathHook: (paths) => paths;

  /** 处理获取oss文件列表钩子 */
  // ossFileHook: (data) => data,

  /** 上传前钩子 */
  // beforeUploadHook: (data) => data,

  /** 删除前钩子 */
  // beforeDeleteHook: (data) => data,
})
  .then(() => {
    // 成功
  })
  .catch(() => {
    // 失败
  });
```

> `UploadOptions` 说明

| 参数               | 说明                                                     | 类型             | 可选项     | 默认值  |
| ------------------ | -------------------------------------------------------- | ---------------- | ---------- | ------- |
| `dirPath`          | 目录路径                                                 | `string`         | 必填       | -       |
| `diff`             | 开启本地文件和 oss 文件进行对比，支持命令行参数 `--diff` | `boolean`        | -          | `true`  |
| `debug`            | 开启后不进行上传和删除操作，支持命令行参数 `--debug`     | `boolean`        | -          | `false` |
| `version`          | 当前版本号                                               | `string`         | -          | -       |
| `versionLimit`     | 保留版本号目录个数                                       | `number`         | -          | `10`    |
| `isClearVersion`   | 是否开启清除版本号目录                                   | `boolean`        | -          | `false` |
| `localFileHook`    | 处理获取本地文件列表钩子                                 | `(data) => data` | 需要返回值 | -       |
| `ossPathHook`      | 处理 oss 路径列表钩子                                    | `(data) => data` | 需要返回值 | -       |
| `ossFileHook`      | 处理获取 oss 文件列表钩子                                | `(data) => data` | 需要返回值 | -       |
| `beforeUploadHook` | 上传前钩子                                               | `(data) => data` | 需要返回值 | -       |
| `beforeDeleteHook` | 删除前钩子                                               | `(data) => data` | 需要返回值 | -       |

> `diff` 属性详细描述

对比规则:

- 本地存在，oss 不存在: 上传
- 本地存在，oss 存在: 覆盖
- 本地不存在，oss 存在: 删除

### 工具属性和方法说明

#### 属性

| 参数       | 说明                               | 类型                       |
| ---------- | ---------------------------------- | -------------------------- |
| `Mode`     | 构建模式                           | `build \| serve`           |
| `Env`      | 构建环境                           | `tst \| production \| uat` |
| `envName`  | 环境名                             | `测试服 \| UAT \| 正式服`  |
| `isTst`    | 测试环境                           | `boolean`                  |
| `isUat`    | UAT 环境                           | `boolean`                  |
| `isPro`    | 正式环境                           | `boolean`                  |
| `isUpload` | 跳过打包，直接上传                 | `boolean`                  |
| `isDebug`  | 是否开启 debug                     | `boolean`                  |
| `isBuild`  | 打包模式                           | `boolean`                  |
| `isServe`  | 开发模式                           | `boolean`                  |
| `branch`   | 当前分支名                         | `string`                   |
| `_argv`    | 参数解析同`minimist(process.argv)` | `minimist.ParsedArgs`      |
| `spinner`  | spinner 实例                       | `ora.Ora`                  |

#### 方法

**md5**

- 说明: md5 加密
- 类型: `(val: string | Buffer) => string`
- 返回值: `boolean`

**isFile**

- 说明: 文件是否存在
- 类型: `(filePath: string) => boolean`
- 返回值: `boolean`

**getCliParam**

- 说明: 获取命令行参数
- 类型: `() => string[]`
- 返回值: `string[]`

**confirm**

- 说明: 提示确认操作
- 类型: `(message: string) => Promise<boolean>`
- 返回值: `Promise<boolean>`

**verifyBuild**

- 说明:  
  验证打包 git 分支 是否对应  
  `master => 正式`  
  `uat => UAT`
- 类型: `(message: string) => boolean`
- 返回值: `boolean`