@shencom/oss-upload

使用说明

介绍

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

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

安装

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

使用

注意: 需要提前配置秘钥

配置秘钥

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

1. 可以使用 @shencom/cli 创建秘钥 (推荐)

# 全局配置:
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

初始化

• 类型

new OSS(ops: OssOptions): OSS

• 示例

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 时生效
• 示例:

  const list = await CLIENT.list(ossPaths, returnType, options);

head

• 说明: 批量获取 oss 文件的 md5
• 类型: OSS.head(ossFilePaths: string[]): Promise<FileData[]>
• 参数:
  • ossFilePaths: oss 文件路径
• 示例:

  const objects = await CLIENT.head(ossFilePaths);

put

• 说明: 删除 oss 文件
• 类型: OSS.delete(ossPaths: string[]): void
• 参数:
  • ossPaths: oss 文件路径
• 示例:

  await CLIENT.delete(paths);

put

• 说明: 上传文件
• 类型: OSS.put(paths: OssUploadItem[]): void
• 参数:
  • paths: 上传路径对象
• 示例:

  await CLIENT.put(paths);

clearVersionDir

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

  await CLIENT.clearVersionDir(paths, limit);

upload

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

upload 使用说明

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

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