@shencom/oss-upload
Version:
code upload to oss
274 lines (205 loc) • 8.42 kB
Markdown
# @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`