@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