tencent cloud

数据万象

快速入门

下载
聚焦模式
字号
最后更新时间: 2025-07-29 11:26:08

下载与安装

相关资源

对象存储服务的 XML JS SDK 资源 github 地址:XML Node.js SDK。
SDK 快速下载地址:XML Node.js SDK。
演示示例 Demo 下载地址:XML Node.js SDK Demo。
SDK 文档中的所有示例代码请参见 SDK 代码示例。
SDK 更新日志请参见 ChangeLog。
说明:
如果您在使用 SDK 时遇到函数或方法不存在等错误,请先将 SDK 升级到最新版再重试。

环境依赖

1. 使用 SDK 需要您的运行环境包含 nodejs 以及 npm,其中 nodejs 版本要求 ≥ 6。
2. 登录 对象存储控制台 创建存储桶后,获取存储桶名称和 地域名称。
3. 登录 访问管理控制台 获取您的项目 SecretId 和 SecretKey。
说明:
关于本文中出现的 SecretId、SecretKey、Bucket 等名称的含义和获取方式请参见 COS 术语信息。

安装 SDK

通过 npm 安装环境 SDK: npm 地址。
npm i cos-nodejs-sdk-v5 --save

开始使用

初始化

注意:
建议用户 使用临时密钥 调用 SDK,通过临时授权的方式进一步提高 SDK 使用的安全性。申请临时密钥时,请遵循 最小权限指引原则,防止泄漏目标存储桶或对象之外的资源。
如果您一定要使用永久密钥,建议遵循 最小权限指引原则 对永久密钥的权限范围进行限制。

使用临时密钥初始化(推荐)

临时密钥生成和使用请参见 临时密钥生成及使用指引。Node.js SDK 支持通过传入临时密钥进行初始化,请参考以下示例代码:
var request = require('request');
var COS = require('cos-nodejs-sdk-v5');
var cos = new COS({
getAuthorization: function (options, callback) {
// 初始化时不会调用,只有调用 cos 方法(例如 cos.putObject)时才会进入
// 异步获取临时密钥
request({
url: 'https://example.com/sts',
data: {
// 可从 options 取需要的参数
}
}, function (err, response, body) {
try {
var data = JSON.parse(body);
var credentials = data.credentials;
} catch(e) {}
if (!data || !credentials) return console.error('credentials invalid');
callback({
TmpSecretId: credentials.tmpSecretId, // 临时密钥的 tmpSecretId
TmpSecretKey: credentials.tmpSecretKey, // 临时密钥的 tmpSecretKey
SecurityToken: credentials.sessionToken, // 临时密钥的 sessionToken
ExpiredTime: data.expiredTime, // 临时密钥失效时间戳,是申请临时密钥时,时间戳加 durationSeconds
});
});
}
});

使用永久密钥初始化(不推荐)

使用永久密钥初始化时,请注意保管好密钥,防止泄露。 请先在访问管理控制台中的 API 密钥管理 页面获取 SecretId、SecretKey。 将 SecretId、SecretKey、Bucket 和 Region 修改为您实际开发环境下的值,测试上传文件,请参考以下示例代码:
// SECRETID 和 SECRETKEY 请登录 https://console.tencentcloud.com/cam/capi 进行查看和管理
var COS = require('cos-nodejs-sdk-v5');
var cos = new COS({
SecretId: process.env.SecretId, // 推荐使用环境变量获取;用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参考https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
SecretKey: process.env.SecretKey, // 推荐使用环境变量获取;用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参考https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
});
以下是部分常用接口例子,更详细的初始化方法请参见 demo 示例。

配置项

构造函数参数说明

参数名
参数描述
类型
是否必填
SecretId
用户的 SecretId
String
是
SecretKey
用户的 SecretKey
String
是
FileParallelLimit
同一个实例下上传的文件并发数,默认值3
Number
否
ChunkParallelLimit
同一个上传文件的分块并发数,默认值3
Number
否
ChunkRetryTimes
分块上传及分块复制时,出错重试次数,默认值2(加第一次,请求共3次)
Number
否
ChunkSize
分块上传时,每块的字节数大小,单位为 Byte,默认值1048576(1MB)
Number
否
SliceSize
使用 uploadFiles 批量上传时,文件大小大于该数值将使用按分片上传,否则将调用简单上传,单位 Byte,默认值1048576(1MB)
Number
否
CopyChunkParallelLimit
进行分块复制操作中复制分块上传的并发数,默认值20
Number
否
CopyChunkSize
使用 sliceCopyFile 分块复制文件时,每片的大小字节数,单位为 Byte,默认值10485760(10MB)
Number
否
CopySliceSize
使用 sliceCopyFile 分片复制文件时,文件大小大于该数值将使用分片复制 ,否则将调用简单复制,单位为 Byte,默认值10485760(10MB)
Number
否
ProgressInterval
上传进度的回调方法 onProgress 的回调频率,单位 ms ,默认值1000
Number
否
Protocol
发请求时用的协议,可选项 https:、http:,默认判断当前页面是 http: 时使用 http:,否则使用 https:
String
否
ServiceDomain
调用 getService 方法时,请求的域名,例如 service.cos.myqcloud.com
String
否
Domain
调用操作存储桶和对象的 API 时自定义请求域名。可以使用模板,例如"{Bucket}.cos.{Region}.myqcloud.com" ,即在调用 API 时会使用参数中传入的 Bucket 和 Region 进行替换
String
否
UploadQueueSize
上传队列最长大小,超出队列大小并失败/已完成/已取消状态的任务会被清理,默认1000
Number
否
ForcePathStyle
强制使用后缀式模式发请求。后缀式模式中 Bucket 会放在域名后的 pathname 里,并且 Bucket 会加入签名 pathname 计算,默认 false
Boolean
否
UploadCheckContentMd5
强制上传文件也校验 Content-MD5,会对文件请求 Body 计算 md5 放在 header 的 Content-MD5 字段里,默认 false
Boolean
否
Timeout
超时时间,单位毫秒,默认为0,即不设置超时时间
Number
否
KeepAlive
多个请求同用 TCP 连接,默认 true,若请求并发量大建议 打开
Boolean
否
StrictSsl
严格校验 HTTPS 证书,默认 true
Boolean
否
Proxy
请求时使用 HTTP 代理,例如:http://127.0.0.1:8080
String
否
getAuthorization
获取签名的回调方法,如果没有 SecretId、SecretKey 时,这个参数必选
Function
否
UseAccelerate
是否启用全球加速域名,默认为 false。若改为 true,需要存储桶开启全球加速功能,详情请参见 开启全球加速。
Boolean
否

getAuthorization 回调函数说明的函数说明(使用格式一)

getAuthorization: function(options, callback) { ... }
getAuthorization 的函数说明:
参数名
参数描述
类型
options
获取临时密钥需要的参数对象
Object
- Bucket
存储桶的名称,命名规则为 BucketName-APPID,此处填写的存储桶名称必须为此格式
String
- Region
存储桶所在地域,枚举值请参见 地域和访问域名
String
callback
临时密钥获取完成后的回传方法
Function
获取完临时密钥后,callback 回传一个对象,回传对象的属性列表如下:
属性名
参数描述
类型
是否必填
TmpSecretId
获取回来的临时密钥的 tmpSecretId
String
是
TmpSecretKey
获取回来的临时密钥的 tmpSecretKey
String
是
SecurityToken
获取回来的临时密钥的 sessionToken,对应 header 的 x-cos-security-token 字段
String
是
StartTime
密钥获取的开始时间,即获取时刻的时间戳,单位秒,startTime,如:1580000000,用于签名开始时间,传入该参数可避免前端时间偏差签名过期问题
String
否
ExpiredTime
获取回来的临时密钥的 expiredTime,超时时刻的时间戳,单位秒,如:1580000900
String
是

getAuthorization 回调函数说明(使用格式二)

getAuthorization: function(options, callback) { ... }
getAuthorization 的函数说明:
参数名
参数描述
类型
options
获取签名需要的参数对象
Object
- Method
当前请求的 Method
String
- Pathname
请求路径,用于签名计算
String
- Key
对象键(Object 的名称),对象在存储桶中的唯一标识,了解更多请参见 对象概述
String
- Query
当前请求的 query 参数对象,{key: 'val'} 的格式
Object
- Headers
当前请求的 header 参数对象,{key: 'val'} 的格式
Object
callback
临时密钥获取完成后的回调
Function
getAuthorization 计算完成后,callback 回传参数支持两种格式: 格式一:回传鉴权凭证字符串 Authorization。 格式二:回传一个对象,对象属性列表如下:
属性名
参数描述
类型
是否必填
Authorization
计算得到的签名字符串
String
是
SecurityToken
获取回来的临时密钥的 sessionToken,对应 header 的 x-cos-security-token 字段
String
否

获取鉴权凭证

实例本身鉴权凭证可以通过实例化时传入的参数控制如何或获取,有三种获取方式:
1. 实例化时,传入 SecretId、SecretKey,每次需要签名都由实例内部计算。
2. 实例化时,传入 getAuthorization 回调,每次需要签名通过这个回调计算完返回签名给实例。
3. 实例化时,传入 getSTS 回调,每次需要临时密钥通过这个回调回去完返回给实例,在每次请求时实例内部使用临时密钥计算得到签名。

使用方式

回调方式

文档里默认使用回调方式,使用代码如下:
// 这里省略初始化过程和上传参数
var cos = new COS({ ... });
cos.uploadFile({ ... }, function(err, data) {
if (err) {
console.log('上传出错', err);
} else {
console.log('上传成功', data);
}
});

Promise

sdk同样支持 Promise 方式调用,例如上述回调方式的代码等同于以下代码:
// 这里省略初始化过程和上传参数
var cos = new COS({ ... });
cos.uploadFile({ ... }).then(data => {
console.log('上传成功', data);
}).catch(err => {
console.log('上传出错', err);
});

同步方式

同步方式基于 JavaScript 的 async 和 await,上述回调方式的代码等同于以下代码:
async function upload() {
// 这里省略初始化过程和上传参数
var cos = new COS({ ... });
try {
var data = await cos.uploadFile({ ... });
return { err: null, data: data }
} catch (err) {
return { err: err, data: null };
}
}
// 可以同步拿到请求的返回值,这里举例说明,实际返回的数据格式可以自定义
var uploadResult = await upload();
if (uploadResult.err) {
console.log('上传出错', uploadResult.err);
} else {
console.log('上传成功', uploadResult.data);
}
注意:
cos.getObjectUrl 目前只支持回调方式。

使用技巧

通常情况下我们只需要创建一个 COS SDK 实例,然后在需要调用SDK方法的地方直接使用这个实例即可,示例代码如下:
var cos = new COS({
....
});

/* 自己封装的上传方法 */
function myUpload() {
// 不需要在每个方法里创建一个 COS SDK 实例
// var cos = new COS({
// ...
// });
cos.putObject({
....
});
}

/* 自己封装的删除方法 */
function myDelete() {
// 不需要在每个方法里创建一个 COS SDK 实例
// var cos = new COS({
// ...
// });
cos.deleteObject({
....
});
}
以下是部分常用接口入口,更详细的初始化方法请参见 demo 示例。

创建存储桶

cos.putBucket({
Bucket: 'examplebucket-1250000000',
Region: 'COS_REGION'
}, function(err, data) {
console.log(err || data);
});

查询存储桶列表

cos.getService(function (err, data) {
console.log(data && data.Buckets);
});

上传对象

该接口适用于小文件上传,大文件请使用分块上传接口,详情请参见 对象操作 文档。
cos.putObject({
Bucket: 'examplebucket-1250000000', /* 必须 */
Region: 'COS_REGION', /* 必须 */
Key: 'exampleobject', /* 必须 */
StorageClass: 'STANDARD',
Body: fs.createReadStream('./exampleobject'), // 上传文件对象
onProgress: function(progressData) {
console.log(JSON.stringify(progressData));
}
}, function(err, data) {
console.log(err || data);
});

查询对象列表

cos.getBucket({
Bucket: 'examplebucket-1250000000', /* 必须 */
Region: 'COS_REGION', /* 必须 */
Prefix: 'a/', /* 非必须 */
}, function(err, data) {
console.log(err || data.Contents);
});

下载对象

cos.getObject({
Bucket: 'examplebucket-1250000000', /* 必须 */
Region: 'COS_REGION', /* 必须 */
Key: 'exampleobject', /* 必须 */
Output: fs.createWriteStream('./exampleobject'),
}, function(err, data) {
console.log(err || data);
});

删除对象

cos.deleteObject({
Bucket: 'examplebucket-1250000000', /* 必须 */
Region: 'COS_REGION', /* 必须 */
Key: 'exampleobject' /* 必须 */
}, function(err, data) {
console.log(err || data);
});


帮助和支持

本页内容是否解决了您的问题?

填写满意度调查问卷,共创更好文档体验。

文档反馈