下载与安装
相关资源
SDK 示例 Demo 地址:XML 小程序 SDK Demo。
SDK 更新日志请参见: ChangeLog。
SDK 常见问题请参见:小程序 SDK 常见问题。
说明:
如果您在使用 SDK 时遇到函数或方法不存在等错误,请先将 SDK 升级到最新版再重试。
如果您项目内只用到简单上传的功能,可以选择不引入 SDK 而是使用直传的方式进行上传,可参考 小程序直传实践 实现。
如果您项目必须使用 SDK,建议您将 SDK 相关模块进行分包,避免小程序主包体积过大。
环境依赖
1. 该 SDK 只适用于微信小程序环境。
3. 登录 访问管理控制台 获取您的项目 SecretId 和 SecretKey。
说明:
关于本文中出现的 SecretId、SecretKey、Bucket 等名称的含义和获取方式请参见 COS 术语信息。
关于跨端框架(例如 uni-app)的使用说明,使用小程序 SDK 开发后无法打包成正常使用的移动应用,例如 Android App、iOS App,需要使用对应的 Android SDK、iOS SDK。
XCosSecurityToken 字段说明:v1.2.0之前版本的 SDK 只支持 XCosSecurityToken,v1.2.0及之后的版本请使用 SecurityToken 代替。
安装 SDK
安装小程序 SDK 有两种方式:手动安装和 npm 安装,具体安装方法如下。
手动安装
const COS = require('./lib/cos-wx-sdk-v5.js'); // 开发时使用// const COS = require('./lib/cos-wx-sdk-v5.min.js'); // 上线时使用压缩包
npm 安装
如果小程序代码使用了 webpack 打包,则通过 npm 安装依赖即可:
npm install cos-wx-sdk-v5
说明:
如果您项目内只用到简单上传的功能,可以选择不引入 SDK 而是使用直传的方式进行上传,可参考 小程序直传实践 实现。
如果您项目必须使用 SDK,建议您将 SDK 相关模块进行分包,避免小程序主包体积过大。
为了您的业务安全,上传文件可参见 上传安全限制。
开始使用
小程序域名白名单配置
1. cos.postObject 使用 wx.uploadFile 方法。
2. 其他方法使用 wx.request 方法。
需要在对应白名单里,配置 COS 域名,例如:
examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com
。初始化
必须引入 SDK 完成初始化 cos 实例,才可以调用 sdk 的方法,例如 cos.uploadFile、cos.getObject。
SDK 内部需要通过密钥生成签名,密钥相关的初始化请参考以下示例。
适用于单次上传动作,适合无需考虑临时密钥过期的场景,该密钥仅用于本次 COS 操作。
const COS = require('./lib/cos-wx-sdk-v5.js'); // 开发时使用// const COS = require('./lib/cos-wx-sdk-v5.min.js'); // 上线时使用压缩包// console.log(COS.version); sdk 版本需要不低于 1.7.2const cos = new COS({SecretId: 'your_tmpSecretId', // sts服务下发的临时 secretIdSecretKey: 'your_tmpSecretKey', // sts服务下发的临时 secretKeySecurityToken: 'your_sessionToken', // sts服务下发的临时 SessionTokenStartTime: 1720770679403, // 建议传入服务端时间,可避免客户端时间不准导致的签名错误ExpiredTime: 1720771991367, // 临时密钥过期时间SimpleUploadMethod: 'putObject', // 强烈建议,高级上传、批量上传内部对小文件做简单上传时使用putObject,sdk版本至少需要v1.3.0});
上传文件实践:
采用回调的方式给 COS SDK 提供获取临时密钥的方法,SDK 会在首次和缓存的临时密钥快过期时使用该回调重新获取临时密钥。
适用于全局初始化一个 cos 实例,方便进行上传文件的队列控制,暂停 、重启等操作。
const COS = require('./lib/cos-wx-sdk-v5.js'); // 开发时使用// const COS = require('./lib/cos-wx-sdk-v5.min.js'); // 上线时使用压缩包const cos = new COS({SimpleUploadMethod: 'putObject', // 强烈建议,高级上传、批量上传内部对小文件做简单上传时使用putObject,sdk版本至少需要v1.3.0getAuthorization: async function (options, callback) {const data = await fetchSts('xxxx'); // 需自行实现获取临时密钥逻辑callback({TmpSecretId: data.credentials.tmpSecretId,TmpSecretKey: data.credentials.tmpSecretKey,SecurityToken: data.credentials.sessionToken,// 建议返回服务器时间作为签名的开始时间,避免客户端本地时间偏差过大导致签名错误StartTime: data.startTime, // 时间戳,单位秒,如:1580000000ExpiredTime: data.expiredTime, // 时间戳,单位秒,如:1580000000ScopeLimit: true, // 细粒度控制权限需要设为 true,会限制密钥只在相同请求时重复使用});}});
例如新建一个 utils/cos.js,项目内全局使用:
const COS = require('./lib/cos-wx-sdk-v5.js'); // 开发时使用// const COS = require('./lib/cos-wx-sdk-v5.min.js'); // 上线时使用压缩包const cos = new COS({SimpleUploadMethod: 'putObject', // 强烈建议,高级上传、批量上传内部对小文件做简单上传时使用putObject,sdk版本至少需要v1.3.0getAuthorization: function (options, callback) {// 初始化时不会调用,只有调用 cos 方法(例如 cos.putObject)时才会进入// 异步获取临时密钥// 服务端 JS 示例:https://github.com/tencentyun/cos-js-sdk-v5/blob/master/server/// 服务端其他语言参考 COS STS SDK :https://github.com/tencentyun/qcloud-cos-sts-sdk// STS 详细文档指引看:https://cloud.tencent.com/document/product/436/14048const stsUrl = 'http://example.com/server/sts'; // stsUrl 替换成您自己的后端服务wx.request({url: stsUrl,data: {bucket: options.Bucket,region: options.Region,},dataType: 'json',success: function (result) {const data = result.data;const credentials = data && data.credentials;if (!data || !credentials) return console.error('credentials invalid');// 检查credentials格式console.log(credentials);callback({TmpSecretId: credentials.tmpSecretId,TmpSecretKey: credentials.tmpSecretKey,// v1.2.0之前版本的 SDK 使用 XCosSecurityToken 而不是 SecurityTokenSecurityToken: credentials.sessionToken,// 建议返回服务器时间作为签名的开始时间,避免用户浏览器本地时间偏差过大导致签名错误StartTime: data.startTime, // 时间戳,单位秒,如:1580000000ExpiredTime: data.expiredTime, // 时间戳,单位秒,如:1580000900});}});}});export default cos;
pageA.js 引用上方导出的 cos 实例
import cos from 'utils/cos';let taskId;// 上传文件,file为选择的文件async function upload(file) {try {const data = await cos.uploadFile({Bucket: 'examplebucket-1250000000', // 填写自己的 bucket,必须字段Region: 'COS_REGION', // 存储桶所在地域,必须字段Key: '1.jpg', // 存储在桶里的对象键(例如1.jpg,a/b/test.txt),必须字段FilePath: file.path, /* 必须 */FileSize: file.size, /* v1.4.3之前的版本必须,v1.4.3及以后的版本非必须 */SliceSize: 1024 * 1024 * 5, // 触发分块上传的阈值,超过5MB 使用分块上传,小于5MB使用简单上传。可自行设置,非必须onProgress: function(progressData) {console.log('上传进度:', progressData);},onTaskReady: function(id) { // 非必须taskId = id;},});console.log('上传成功', data);} catch (e) {console.error('上传失败', e);}}// 监听上传队列cos.on('update-list', data => {console.log(data);});// 暂停上传任务cos.pauseTask(taskId);// 重启上传任务cos.restartTask(taskId);// 取消上传任务cos.cancelTask(taskId);lli
您可以使用腾讯云的永久密钥来进行开发阶段的本地调试。由于该方式存在泄露密钥的风险,请务必在上线前替换为临时密钥的方式。
const COS = require('./lib/cos-wx-sdk-v5.js'); // 开发时使用// const COS = require('./lib/cos-wx-sdk-v5.min.js'); // 上线时使用压缩包// SECRETID 和 SECRETKEY 请登录 https://console.cloud.tencent.com/cam/capi 进行查看和管理const cos = new COS({SecretId: process.env.SecretId, // 推荐使用环境变量获取;用户的 SecretId,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参考https://cloud.tencent.com/document/product/598/37140SecretKey: process.env.SecretKey, // 推荐使用环境变量获取;用户的 SecretKey,建议使用子账号密钥,授权遵循最小权限指引,降低使用风险。子账号密钥获取可参考https://cloud.tencent.com/document/product/598/37140});
初始化配置项
其他初始化参数请参考以下 new COS(options) 构造函数参数说明:
参数名 | 参数描述 | 类型 | 是否必填 |
SecretId | 用户的 SecretId,建议只在前端调试时使用,避免暴露密钥 | String | 否 |
SecretKey | 用户的 SecretKey,建议只在前端调试时使用,避免暴露密钥 | String | 否 |
SecurityToken | 获取回来的临时密钥的 sessionToken(v1.7.2 版本开始支持)。当 SecretId、SecretKey 传入临时密钥时,SecurityToken 必填。 | String | 否 |
StartTime | 获取回来的临时密钥的有效起始时间戳(v1.7.2 版本开始支持),单位:秒。当 SecretId、SecretKey 传入临时密钥时,建议传入 StartTime。 | Number | 否 |
ExpiredTime | 获取回来的临时密钥的有效过期时间戳(v1.7.2 版本开始支持),单位:秒。当 SecretId、SecretKey 传入临时密钥时,建议传入 ExpiredTime。 | Number | 否 |
FileParallelLimit | 同一个实例下上传的文件并发数,默认值3 | Number | 否 |
ChunkParallelLimit | 同一个上传文件的分块并发数,默认值3 | Number | 否 |
ChunkRetryTimes | 分块上传及分块复制时,出错重试次数,默认值2(加第一次,请求共3次) | Number | 否 |
ChunkSize | 分块上传时,每块的字节数大小,默认值1048576(1MB) | Number | 否 |
SliceSize | 使用 uploadFiles 批量上传时,文件大小大于该数值就使用分块上传 sliceUploadFile,否则使用简单上传 putObject,默认值1048576(1MB) | Number | 否 |
CopyChunkParallelLimit | 进行分块复制操作中复制分块上传的并发数,默认值20 | Number | 否 |
CopyChunkSize | 使用 sliceCopyFile 分块复制文件时,每块的大小字节数,默认值10485760(10MB) | Number | 否 |
CopySliceSize | 使用 sliceCopyFile 分块复制文件时,文件大小大于该数值就会使用分块复制 sliceCopyFile ,否则使用简单复制 putObjectCopy,默认值10485760(10MB) | Number | 否 |
ProgressInterval | 上传进度的回调方法 onProgress 的回调频率,单位 ms ,默认值1000 | Number | 否 |
Protocol | 发请求时用的协议,可选项 https: 、http: ,小程序里只能使用https | String | 否 |
ServiceDomain | 调用 getService 方法时,请求的域名,例如 service.cos.myqcloud.com | String | 否 |
Domain | 调用操作存储桶和对象的 API 时自定义请求域名。可以使用模板,例如 "{Bucket}.cos.{Region}.myqcloud.com" ,即在调用 API 时会使用参数中传入的 Bucket 和 Region 进行替换 | String | 否 |
UploadQueueSize | 上传队列最长大小,超出的任务如果状态不是 waiting、checking、uploading 会被清理,默认10000 | Number | 否 |
UploadCheckContentMd5 | 强制上传文件校验 Content-MD5,会对文件请求 Body 计算 md5 放在 header 的 Content-MD5 字段里,默认为 false | Boolean | 否 |
getAuthorization | 获取签名的回调方法,如果没有 SecretId、SecretKey 时,这个参数必选。 注意: 该回调方法在初始化实例时传入,在使用实例调用接口时才会执行并获取签名。 | Function | 否 |
UseAccelerate | Boolean | 否 | |
SimpleUploadMethod | 高级上传、批量上传内部对小文件做简单上传的方法名,可选'postObject'或'putObject',默认为'postObject'(该参数v1.3.0版本开始支持) | String | 否 |
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 字段。v1.2.0之前版本的 SDK 使用 XCosSecurityToken 而不是 SecurityToken | String | 是 |
StartTime | 密钥获取的开始时间,即获取时刻的时间戳,单位秒,startTime,如:1580000000,用于签名开始时间,传入该参数可避免前端时间偏差签名过期问题 | String | 否 |
ExpiredTime | 获取回来的临时密钥的 expiredTime,超时时刻的时间戳,单位秒,如:1580000900 | String | 是 |
获取鉴权凭证
实例本身鉴权凭证可以通过实例化时传入的参数控制如何获取,有三种获取方式:
1. 实例化时,传入 SecretId、SecretKey,每次需要签名都由实例内部计算。
2. 实例化时,传入 getAuthorization 回调,每次需要签名通过这个回调计算完返回签名给实例。
3. 实例化时,传入 getSTS 回调,每次需要临时密钥通过这个回调返回给实例,在每次请求时实例内部使用临时密钥计算得到签名。
开启 beacon 上报
说明:
腾讯灯塔只对 COS 侧的请求性能进行监控,不会上报业务侧数据。
若是想开启该功能,请先确保 SDK 版本升级到1.6.2及以上,然后在初始化中传入 BeaconReporter。
并在小程序域名白名单中 request 合法域名里添加:
https://h.trace.qq.com;https://oth.str.beacon.qq.com;https://otheve.beacon.qq.com。
// 完整demo可参考:https://github.com/tencentyun/cos-wx-sdk-v5/blob/master/demo/tools.jsconst Beacon = require('./lib/beacon_mp.min');new COS({BeaconReporter,})
使用方式
回调方式
文档里默认使用回调方式,使用代码如下:
// 这里省略初始化过程和上传参数const cos = new COS({ ... });cos.uploadFile({ ... }, function(err, data) {if (err) {console.log('上传出错', err);} else {console.log('上传成功', data);}});
Promise
sdk 同样支持 Promise 方式调用,例如上述回调方式的代码等同于以下代码:
// 这里省略初始化过程和上传参数const cos = new COS({ ... });cos.uploadFile({ ... }).then(data => {console.log('上传成功', data);}).catch(err => {console.log('上传出错', err);});
同步方式
同步方式基于 JavaScript 的 async 和 await,上述回调方式的代码等同于以下代码:
async function upload() {// 这里省略初始化过程和上传参数const cos = new COS({ ... });try {const data = await cos.uploadFile({ ... });return { err: null, data: data }} catch (err) {return { err: err, data: null };}}// 可以同步拿到请求的返回值,这里举例说明,实际返回的数据格式可以自定义const uploadResult = await upload();if (uploadResult.err) {console.log('上传出错', uploadResult.err);} else {console.log('上传成功', uploadResult.data);}
注意:
cos.getObjectUrl 目前只支持回调方式。
常见接口
创建存储桶
cos.putBucket({Bucket: 'examplebucket-1250000000',Region: 'ap-beijing',}, function (err, data) {console.log(err || data);});
注意:
查询存储桶列表
cos.getService(function (err, data) {console.log(data && data.Buckets);});
上传对象
强烈推荐使用高级上传接口 uploadFile,自动针对小文件使用简单上传,大文件使用分块上传,性能更好。详情请参见 高级上传 文档。
若使用临时密钥方式,需同时授权
简单上传对象
和分块上传
的权限。请参考授权指引。
常见上传错误排查,请参考 常见问题。/* 初始化cos */const cos = new COS({// getAuthorization: funciton() {}, // 参考上方初始化SimpleUploadMethod: 'putObject', // 强烈建议,高级上传、批量上传内部对小文件做简单上传时使用putObject});function handleFileInUploading(fileName, filePath) {cos.uploadFile({Bucket: 'examplebucket-1250000000', /* 填写自己的 bucket,必须字段 */Region: 'COS_REGION', /* 存储桶所在地域,必须字段 */Key: fileName, /* 存储在桶里的对象键(例如:1.jpg,a/b/test.txt,图片.jpg)支持中文,必须字段 */FilePath: filePath, /* 上传文件路径,必须字段 */SliceSize: 1024 * 1024 * 5, /* 触发分块上传的阈值,超过5MB使用分块上传,小于5MB使用简单上传。可自行设置,非必须 */onProgress: function(progressData) {console.log(JSON.stringify(progressData));}}, function(err, data) {if (err) {console.log('上传失败', err);} else {console.log('上传成功');}});}/* 选择文件,得到临时路径(以选择图片为例,选择其他文件请参考小程序官方api) */wx.chooseImage({count: 1, // 默认9sizeType: ['original'], // 可以指定是原图还是压缩图,默认用原图sourceType: ['album', 'camera'], // 可以指定来源是相册还是相机,默认二者都有success: function (res) {const filePath = res.tempFiles[0].path;const fileName = filePath.substr(filePath.lastIndexOf('/') + 1);handleFileInUploading(fileName, filePath);}});
查询对象列表
cos.getBucket({Bucket: 'examplebucket-1250000000',Region: 'ap-beijing',Prefix: 'exampledir/', // 这里传入列出的文件前缀}, function (err, data) {console.log(err || data.Contents);});
下载对象
注意:
cos.getObject({Bucket: 'examplebucket-1250000000',Region: 'ap-beijing',Key: 'exampleobject.txt',}, function (err, data) {console.log(err || data.Body);});
删除对象
cos.deleteObject({Bucket: 'examplebucket-1250000000',Region: 'ap-beijing',Key: 'picture.jpg',}, function (err, data) {console.log(err || data);});