T Comm

引入

import {
  unfreezeCosImage,
  batchUnfreezeCosImages,
  getCosBucket,
  uploadCOSFile,
  getCOSBucketList,
  deleteCOSMultipleObject,
  getCOSInstance,
  onUploadCOSProgress,
  getCosHeadObject,
  downloadCosObject,
  isCosObjectSameAsLocal,
  uploadCOSStreamFile,
  uploadCOSStreamFileV2,
  getCosObjectUrl
} from 't-comm';

// 不支持 tree-shaking 的项目
import {
  unfreezeCosImage,
  batchUnfreezeCosImages,
  getCosBucket,
  uploadCOSFile,
  getCOSBucketList,
  deleteCOSMultipleObject,
  getCOSInstance,
  onUploadCOSProgress,
  getCosHeadObject,
  downloadCosObject,
  isCosObjectSameAsLocal,
  uploadCOSStreamFile,
  uploadCOSStreamFileV2,
  getCosObjectUrl
} from 't-comm/lib/tencent-cloud/cos/index';

// 只支持 ESM 的项目
import {
  unfreezeCosImage,
  batchUnfreezeCosImages,
  getCosBucket,
  uploadCOSFile,
  getCOSBucketList,
  deleteCOSMultipleObject,
  getCOSInstance,
  onUploadCOSProgress,
  getCosHeadObject,
  downloadCosObject,
  isCosObjectSameAsLocal,
  uploadCOSStreamFile,
  uploadCOSStreamFileV2,
  getCosObjectUrl
} from 't-comm/es/tencent-cloud/cos/index';

`unfreezeCosImage(config)`

描述：解除腾讯云 COS 图片封禁

当图片因内容审核被封禁后，可调用此方法解除封禁
底层通过 putObjectCopy 设置 x-cos-forbid-state: 0 来解除封禁状态

Throws:

当参数不全时会抛出错误

参数：

参数名	类型	描述
config	`object`	配置信息
config.secretId	`string`	腾讯云 SecretId
config.secretKey	`string`	腾讯云 SecretKey
config.bucket	`string`	COS 存储桶名称（如 'my-bucket-1250000000'）
config.region	`string`	COS 存储桶所在区域（如 'ap-guangzhou'）
config.key	`string`	被封禁的对象键（Object Key），即图片在存储桶中的路径

返回: Promise.<object>

解封结果

示例

// 解除单张图片的封禁
await unfreezeCosImage({
  secretId: 'your-secret-id',
  secretKey: 'your-secret-key',
  bucket: 'my-bucket-1250000000',
  region: 'ap-guangzhou',
  key: 'images/photo.jpg',
});

`batchUnfreezeCosImages(config)`

描述：批量解除腾讯云 COS 图片封禁

对多张被封禁的图片并行执行解封操作
底层通过 Promise.allSettled 并发调用 unfreezeCosImage

参数：

参数名	类型	描述
config	`object`	配置信息
config.secretId	`string`	腾讯云 SecretId
config.secretKey	`string`	腾讯云 SecretKey
config.bucket	`string`	COS 存储桶名称（如 'my-bucket-1250000000'）
config.region	`string`	COS 存储桶所在区域（如 'ap-guangzhou'）
config.keys	`Array<string>`	被封禁的对象键列表

返回: Promise.<Array<object>>

每张图片的解封结果数组，包含 key、success、data/error 字段

示例

const results = await batchUnfreezeCosImages({
  secretId: 'your-secret-id',
  secretKey: 'your-secret-key',
  bucket: 'my-bucket-1250000000',
  region: 'ap-guangzhou',
  keys: ['images/photo1.jpg', 'images/photo2.jpg'],
});

results.forEach(r => {
  if (r.success) {
    console.log(`${r.key} 解封成功`);
  } else {
    console.error(`${r.key} 解封失败:`, r.error);
  }
});

`getCosBucket(secretId, secretKey, bucket, region, prefix, delimiter, maxKeys, marker, encodingType)`

描述：获取腾讯云COS存储桶中的对象列表

Throws:

当参数不全时会抛出错误

参数：

参数名	描述
secretId	腾讯云API密钥ID
secretKey	腾讯云API密钥Key
bucket	COS存储桶名称
region	COS存储桶所在区域
prefix	对象键前缀匹配，限定返回中只包含指定前缀的对象键（可选）
delimiter	定界符，用于对对象键进行分组，一般是传/（可选）
maxKeys	单次返回最大的条目数量，默认1000，最大为1000（可选）
marker	起始对象键标记，列出从Marker开始MaxKeys条目（可选）
encodingType	返回值的编码方式，可选值：url（可选）

返回: Promise对象，成功时返回存储桶内容数据，失败时返回错误信息

示例

typescript

getCosBucket({
  secretId: 'your-secret-id',
  secretKey: 'your-secret-key',
  bucket: 'test-bucket',
  region: 'ap-beijing'
})
.then(data => console.log(data))
.catch(err => console.error(err));

`uploadCOSFile(config)`

描述：COS上传

参数：

参数名	类型	描述
config	`object`	配置信息
config.files	`Array<object>`	文件列表
config.files.key	`string`	文件key
config.files.path	`string`	文件路径
[config.files.ContentType]	`string`	文件 MIME 类型（如 image/svg+xml），不传则由 COS 根据扩展名推断
config.secretId	`string`	COS secretId
config.secretKey	`string`	COS secretKey
config.bucket	`string`	COS bucket
config.region	`string`	COS region

返回: Promise.<object>

请求Promise

示例

typescript

uploadCOSFile({
  files: [{
    key: 'key1',
    path: 'path1',
  }, {
    key: 'key2',
    path: 'path2',
  }],
  secretId: 'xxx',
  secretKey: 'xxx',
  bucket: 'xxx',
  region: 'xxx',
})

`getCOSBucketList(config)`

描述：获取 COS 存储桶中的文件列表

参数：

参数名	类型	描述
config	`object`	配置信息
config.secretId	`string`	COS secretId
config.secretKey	`string`	COS secretKey
config.bucket	`string`	COS bucket
config.region	`string`	COS region
config.prefix	`string`	文件前缀过滤

返回: Promise.<Array<ICosMeta>>

文件元信息列表

示例

const list = await getCOSBucketList({
  secretId: 'xxx',
  secretKey: 'xxx',
  bucket: 'my-bucket-1250000000',
  region: 'ap-guangzhou',
  prefix: 'static/',
});

`deleteCOSMultipleObject(config)`

描述：批量删除 COS 存储桶中的多个对象

参数：

参数名	类型	描述
config	`object`	配置信息
config.secretId	`string`	COS secretId
config.secretKey	`string`	COS secretKey
config.keys	`Array<string>`	要删除的对象 key 列表
config.bucket	`string`	COS bucket
config.region	`string`	COS region

返回: Promise.<any>

删除结果

示例

await deleteCOSMultipleObject({
  secretId: 'xxx',
  secretKey: 'xxx',
  keys: ['static/old-file1.js', 'static/old-file2.js'],
  bucket: 'my-bucket-1250000000',
  region: 'ap-guangzhou',
});

`getCOSInstance(secretId, secretKey)`

描述：获取腾讯云 COS SDK 实例创建并返回一个配置好的 COS 客户端实例

参数：

参数名	描述
secretId	腾讯云 SecretId
secretKey	腾讯云 SecretKey

返回: COS SDK 实例

示例

const cos = getCOSInstance('your-secret-id', 'your-secret-key');
// 使用 cos 实例进行文件操作

`onUploadCOSProgress(info)`

描述：COS 文件上传进度回调函数显示上传进度、速度、已上传大小和总大小

参数：

参数名	描述
info	上传进度信息
info.percent	上传进度百分比（0-1）
info.speed	上传速度（字节/秒）
info.total	文件总大小（字节）
info.loaded	已上传大小（字节）

示例

onUploadCOSProgress({
  percent: 0.5,
  speed: 1024000,
  total: 10240000,
  loaded: 5120000
});
// 输出: 总共：9.77 MB，已上传：4.88 MB，进度：50%，速度：1000.00 KB/s

`getCosHeadObject(secretId, secretKey, bucket, region, key)`

描述：获取腾讯云COS对象的元数据信息（不返回对象内容）

Throws:

当参数不全时会抛出错误

参数：

参数名	描述
secretId	腾讯云API密钥ID
secretKey	腾讯云API密钥Key
bucket	COS存储桶名称
region	COS存储桶所在区域
key	对象键（Object Key），对象在存储桶中的唯一标识

返回: Promise对象，成功时返回对象的元数据信息（如大小、修改时间等），失败时返回错误信息

示例

typescript

getCosHeadObject({
  secretId: 'your-secret-id',
  secretKey: 'your-secret-key',
  bucket: 'test-bucket',
  region: 'ap-beijing',
  key: 'path/to/file.txt'
})
.then(data => console.log(data))
.catch(err => console.error(err));

`downloadCosObject(secretId, secretKey, bucket, region, key, output)`

描述：下载腾讯云COS对象内容

Throws:

当参数不全时会抛出错误

参数：

参数名	描述
secretId	腾讯云API密钥ID
secretKey	腾讯云API密钥Key
bucket	COS存储桶名称
region	COS存储桶所在区域
key	对象键（Object Key），对象在存储桶中的唯一标识
output	输出路径或输出流，可选参数。如果指定，对象内容将写入该路径或流

返回: Promise对象，成功时返回对象内容数据，失败时返回错误信息

示例

typescript

// 下载到内存
downloadCosObject({
  secretId: 'your-secret-id',
  secretKey: 'your-secret-key',
  bucket: 'test-bucket',
  region: 'ap-beijing',
  key: 'path/to/file.txt'
})
.then(data => console.log(data))
.catch(err => console.error(err));

// 下载到文件
downloadCosObject({
  secretId: 'your-secret-id',
  secretKey: 'your-secret-key',
  bucket: 'test-bucket',
  region: 'ap-beijing',
  key: 'path/to/file.txt',
  output: './local/file.txt'
})
.then(data => console.log('下载成功'))
.catch(err => console.error(err));

`isCosObjectSameAsLocal(secretId, secretKey, bucket, region, key, localFilePath)`

描述：判断 COS 对象与本地文件是否一致（基于 size 与 ETag/MD5）实现说明：

优先使用 COS 的 `x-cos-meta-md5`（上传时显式设置的元数据，最可靠）； - 否则使用 ETag（仅当对象为简单上传，即 ETag 不含连字符 `-` 时才视为整体 MD5；分块上传 ETag 不可用于直接比较）。

参数：

参数名	描述
secretId	腾讯云 API 密钥 ID
secretKey	腾讯云 API 密钥 Key
bucket	COS 存储桶名称
region	COS 存储桶所在区域
key	对象键
localFilePath	本地文件路径

返回: Promise.<boolean>

一致返回 true，否则 false（本地文件不存在或对象不存在也返回 false）

示例

typescript

const same = await isCosObjectSameAsLocal({
  secretId, secretKey,
  bucket: 'test-bucket', region: 'ap-beijing',
  key: 'path/to/file.txt',
  localFilePath: './local/file.txt',
});
if (!same) {
  // 重新上传
}

`uploadCOSStreamFile(config)`

描述：以流式方式上传文件到腾讯云 COS（使用 putObject 简单上传）支持通过文件路径或 Buffer 上传，适用于大文件或流式场景注意：单次上传大小限制为 5GB，超大文件请使用 uploadCOSStreamFileV2

参数：

参数名	类型	描述
config	`object`	配置信息
config.file	`object`	文件信息
[config.file.path]	`string`	文件路径（与 buffer 二选一）
config.file.size	`number`	文件大小（字节）
[config.file.buffer]	`Buffer`	文件 Buffer（与 path 二选一）
config.key	`string`	COS 对象键（如 'images/test.png'）
config.secretId	`string`	COS secretId
config.secretKey	`string`	COS secretKey
config.bucket	`string`	COS bucket
config.region	`string`	COS region

返回: Promise.<any>

上传结果

示例

await uploadCOSStreamFile({
  file: { path: '/tmp/test.png', size: 1024 },
  key: 'images/test.png',
  secretId: 'xxx',
  secretKey: 'xxx',
  bucket: 'my-bucket-1250000000',
  region: 'ap-guangzhou',
});

`uploadCOSStreamFileV2(config)`

描述：以高级上传方式上传文件到腾讯云 COS（使用 uploadFile，SDK 自动决定分块或简单上传）适用于大文件上传，支持自动分块和断点续传

参数：

参数名	类型	默认值	描述
config	`object`		配置信息
config.file	`object`		文件信息
config.file.path	`string`		文件路径（必填）
config.file.size	`number`		文件大小（字节）
config.key	`string`		COS 对象键（如 'images/test.png'）
config.secretId	`string`		COS secretId
config.secretKey	`string`		COS secretKey
config.bucket	`string`		COS bucket
config.region	`string`		COS region
[config.sliceSize]	`number`	`5242880`	分块大小，默认 5MB

返回: Promise.<any>

上传结果

示例

await uploadCOSStreamFileV2({
  file: { path: '/tmp/large-file.zip', size: 104857600 },
  key: 'files/large-file.zip',
  secretId: 'xxx',
  secretKey: 'xxx',
  bucket: 'my-bucket-1250000000',
  region: 'ap-guangzhou',
  sliceSize: 1024 * 1024 * 10, // 10MB
});

`getCosObjectUrl(secretId, secretKey, bucket, region, key, sign, expires, method, protocol, domain, query, headers, forceDownload)`

描述：获取腾讯云 COS 存储桶中对象的访问 URL

Throws:

当参数不全时会抛出错误

参数：

参数名	描述
secretId	腾讯云 API 密钥 ID
secretKey	腾讯云 API 密钥 Key
bucket	COS 存储桶名称
region	COS 存储桶所在区域，例如 ap-beijing
key	存储在桶里的对象键（例如 1.jpg、a/b/test.txt），支持中文
sign	是否获取带签名的对象 URL，默认 true（可选）
expires	签名 URL 的有效时长，单位秒，默认 900 秒（可选）
method	请求方法，默认 GET（可选）
protocol	请求协议，可选值：http:、https:（可选）
domain	自定义域名（可选）
query	请求中的 query 参数（可选）
headers	请求中的 header 参数（可选）
forceDownload	是否强制下载，传入下载后的文件名后将拼接 response-content-disposition 参数（可选）

返回: Promise 对象，成功时返回对象访问 URL 字符串，失败时返回错误信息

示例

typescript

getCosObjectUrl({
  secretId: 'your-secret-id',
  secretKey: 'your-secret-key',
  bucket: 'examplebucket-1250000000',
  region: 'ap-beijing',
  key: '头像.jpg',
  sign: true,
})
.then(url => console.log(url))
.catch(err => console.error(err));

引入 ​

unfreezeCosImage(config) ​

batchUnfreezeCosImages(config) ​

getCosBucket(secretId, secretKey, bucket, region, prefix, delimiter, maxKeys, marker, encodingType) ​

uploadCOSFile(config) ​

getCOSBucketList(config) ​

deleteCOSMultipleObject(config) ​

getCOSInstance(secretId, secretKey) ​

onUploadCOSProgress(info) ​

getCosHeadObject(secretId, secretKey, bucket, region, key) ​

downloadCosObject(secretId, secretKey, bucket, region, key, output) ​

isCosObjectSameAsLocal(secretId, secretKey, bucket, region, key, localFilePath) ​

uploadCOSStreamFile(config) ​

uploadCOSStreamFileV2(config) ​

getCosObjectUrl(secretId, secretKey, bucket, region, key, sign, expires, method, protocol, domain, query, headers, forceDownload) ​

引入

`unfreezeCosImage(config)`

`batchUnfreezeCosImages(config)`

`getCosBucket(secretId, secretKey, bucket, region, prefix, delimiter, maxKeys, marker, encodingType)`

`uploadCOSFile(config)`

`getCOSBucketList(config)`

`deleteCOSMultipleObject(config)`

`getCOSInstance(secretId, secretKey)`

`onUploadCOSProgress(info)`

`getCosHeadObject(secretId, secretKey, bucket, region, key)`

`downloadCosObject(secretId, secretKey, bucket, region, key, output)`

`isCosObjectSameAsLocal(secretId, secretKey, bucket, region, key, localFilePath)`

`uploadCOSStreamFile(config)`

`uploadCOSStreamFileV2(config)`

`getCosObjectUrl(secretId, secretKey, bucket, region, key, sign, expires, method, protocol, domain, query, headers, forceDownload)`