图片审核 快速入门（小程序 SDK）

一、相关资源

·对象存储 COS 的小程序 SDK 源码：源码快速下载、GitHub 源码、npm 包。

·SDK 示例 Demo 地址：XML 小程序 SDK Demo。

·SDK 更新日志请参见： ChangeLog。

·SDK 常见问题请参见：小程序 SDK 常见问题。

注意：说明：

二、环境配置与准备

·该 SDK 只适用于微信小程序环境。

·登录 对象存储控制台 创建存储桶后，获取存储桶名称和 地域信息。

·登录 访问管理控制台 获取你的项目 SecretId 和 SecretKey。

注意：说明：

三、安装 SDK

安装小程序 SDK 有两种方式：手动安装和 npm 安装，具体安装方法如下。

四、方式一：手动安装

复制源码文件中的 cos-wx-sdk-v5.js 到自己小程序代码根目录下任意路径，并用相对路径引用：

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

其中，在程序代码中使用 var COS = require('cos-wx-sdk-v5'); 进行引用。更多详情请参见 npm 支持。

注意：说明：

注意：为了你的业务安全，上传文件可参见 上传安全限制。

六、小程序域名白名单配置

小程序里请求 COS 需要登录到 微信公众平台，选择开发 > 开发设置 > 服务器域名，配置域名白名单。SDK 使用了两个接口：

·cos.uploadFile 会调用 wx.uploadFile、wx.request。

·cos.postObject 会调用 wx.uploadFile。

·其他方法会调用 wx.request。

需要在对应白名单里，配置 COS 域名，例如：

examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com。

如果上传走的是全球加速域名，需要配置全球加速域名，例如：

examplebucket-1250000000.cos.accelerate.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 服务下发的临时 secretId SecretKey: 'your_tmpSecretKey', // sts 服务下发的临时 secretKey SecurityToken: 'your_sessionToken', // sts 服务下发的临时 SessionToken StartTime: 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.0 getAuthorization: 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, // 时间戳，单位秒，如：1580000000 ExpiredTime: data.expiredTime, // 时间戳，单位秒，如：1580000000 ScopeLimit: 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.0 getAuthorization: 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/14048 const 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 而不是 SecurityToken SecurityToken: credentials.sessionToken, // 建议返回服务器时间作为签名的开始时间，避免用户浏览器本地时间偏差过大导致签名错误 StartTime: data.startTime, // 时间戳，单位秒，如：1580000000 ExpiredTime: 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);你可以使用腾讯云的永久密钥来进行开发阶段的本地调试。由于该方式存在泄露密钥的风险，请务必在上线前替换为临时密钥的方式。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/37140 SecretKey: process.env.SecretKey, // 推荐使用环境变量获取；用户的 SecretKey，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参考https://cloud.tencent.com/document/product/598/37140});

八、初始化配置项说明

初始化参数getAuthorization 回调函数说明

初始化参数请参考以下 new COS(options) 构造函数参数说明。

getAuthorization: function(options, callback) { … }

getAuthorization 的回调参数说明：

获取完临时密钥后，callback 回传一个对象，该对象的属性列表如下：

九、获取鉴权凭证

实例本身鉴权凭证可以通过实例化时传入的参数控制如何获取，有三种获取方式：

1. 实例化时，传入 SecretId、SecretKey，每次需要签名都由实例内部计算。

2. 实例化时，传入 getAuthorization 回调，每次需要签名通过这个回调计算并返回签名给实例。

3. 实例化时，传入 getSTS 回调，每次需要临时密钥通过这个回调返回给实例，在每次请求时实例内部使用临时密钥计算得到签名。

十、开启 Beacon 上报（可选）

为了持续跟踪和优化 SDK 的质量，给你带来更好的使用体验，我们在 SDK 中引入了 腾讯灯塔 SDK。

注意：说明：

注意：腾讯灯塔只对 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: Beacon,})

十一、使用方式

示例默认使用回调方式，相关代码如下。

注意：cos.getObjectUrl 目前只支持回调方式。

回调方式Promise 方式同步方式// 这里省略初始化过程和上传参数const cos = new COS({ … });cos.uploadFile({ … }, function(err, data) { if (err) { console.log('上传出错', err); } else { console.log('上传成功', data); }});// 这里省略初始化过程和上传参数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 服务

以下是部分常用接口示例，更详细的初始化方法请参见 demo 示例。

创建存储桶查询存储桶列表上传对象查询对象列表下载对象删除对象

注意：如果需要在小程序中创建存储桶，但存储桶名称未知时，无法将存储桶名称配置为域名白名单，可以使用后缀式调用，相关处理措施请参见 常见问题。var COS = require('./lib/cos-wx-sdk-v5');/* 初始化 cos */const cos = new COS({ getAuthorization: function (options, callback) { wx.request({ method: 'GET', url: config.stsUrl, dataType: 'json', success: function (result) { var data = result.data; var credentials = data && data.credentials; if (!data || !credentials) { console.error('获取临时密钥失败'); return; } callback({ TmpSecretId: credentials.tmpSecretId, TmpSecretKey: credentials.tmpSecretKey, SecurityToken: credentials.sessionToken, StartTime: data.startTime, ExpiredTime: data.expiredTime, }); }, fail: function (err) { console.error('请求临时密钥失败:', err); } }); }});function createBucket() { cos.putBucket({ Bucket: 'examplebucket-1250000000', Region: 'ap-beijing' }, function (err, data) { if (err) { console.log('创建存储桶失败', err); } else { console.log('创建存储桶成功', data); console.log('存储桶位置:', data.Location); } });}

var COS = require('./lib/cos-wx-sdk-v5');var config = require('./config');/* 初始化 cos */const cos = new COS({ getAuthorization: function (options, callback) { wx.request({ method: 'GET', url: config.stsUrl, dataType: 'json', success: function (result) { var data = result.data; var credentials = data && data.credentials; if (!data || !credentials) { console.error('获取临时密钥失败'); return; } callback({ TmpSecretId: credentials.tmpSecretId, TmpSecretKey: credentials.tmpSecretKey, SecurityToken: credentials.sessionToken, StartTime: data.startTime, ExpiredTime: data.expiredTime, }); }, fail: function (err) { console.error('请求临时密钥失败:', err); } }); }});/* 获取存储桶列表 */function getBucketList() { cos.getService(function (err, data) { if (err) { console.log('获取存储桶列表失败', err); } else { console.log('获取存储桶列表成功', 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, // 默认9 sizeType: ['original'], // 可以指定是原图还是压缩图，默认用原图 sourceType: ['album', 'camera'], // 可以指定来源是相册还是相机，默认二者都有 success: function (res) { const filePath = res.tempFiles[0].path; const fileName = filePath.substr(filePath.lastIndexOf('/') + 1); handleFileInUploading(fileName, filePath); }});

var COS = require('./lib/cos-wx-sdk-v5');var config = require('./config');/* 初始化 cos */const cos = new COS({ getAuthorization: function (options, callback) { wx.request({ method: 'GET', url: config.stsUrl, dataType: 'json', success: function (result) { var data = result.data; var credentials = data && data.credentials; if (!data || !credentials) { console.error('获取临时密钥失败'); return; } callback({ TmpSecretId: credentials.tmpSecretId, TmpSecretKey: credentials.tmpSecretKey, SecurityToken: credentials.sessionToken, StartTime: data.startTime, ExpiredTime: data.expiredTime, }); }, fail: function (err) { console.error('请求临时密钥失败:', err); } }); }});/* 获取存储桶中的对象列表 */function getObjectList() { cos.getBucket({ Bucket: 'examplebucket-1250000000', Region: 'ap-beijing', Prefix: 'exampledir/', // 这里传入列出的文件前缀 }, function (err, data) { if (err) { console.log('获取对象列表失败', err); } else { console.log('获取对象列表成功', data); console.log(err || data.Contents); } });}

注意：该接口用于读取对象内容，如果需要发起小程序下载文件，可以通过 cos.getObjectUrl 获取 url 再触发小程序下载，具体参见 预签名 URL 文档。var COS = require('./lib/cos-wx-sdk-v5');var config = require('./config');/* 初始化 cos */const cos = new COS({ getAuthorization: function (options, callback) { wx.request({ method: 'GET', url: config.stsUrl, dataType: 'json', success: function (result) { var data = result.data; var credentials = data && data.credentials; if (!data || !credentials) { console.error('获取临时密钥失败'); return; } callback({ TmpSecretId: credentials.tmpSecretId, TmpSecretKey: credentials.tmpSecretKey, SecurityToken: credentials.sessionToken, StartTime: data.startTime, ExpiredTime: data.expiredTime, }); }, fail: function (err) { console.error('请求临时密钥失败:', err); } }); }});/* 下载对象 */function getObject() { cos.getObject({ Bucket: 'examplebucket-1250000000', Region: 'ap-beijing', Key: 'exampleobject.txt', }, function (err, data) { if (err) { console.log('下载对象失败', err); } else { console.log('下载对象成功', data); console.log(err || data.Body); } });}

注意：对象被删除后，其对应的数据将无法再被访问。var COS = require('./lib/cos-wx-sdk-v5');var config = require('./config');/* 初始化 cos */const cos = new COS({ getAuthorization: function (options, callback) { wx.request({ method: 'GET', url: config.stsUrl, dataType: 'json', success: function (result) { var data = result.data; var credentials = data && data.credentials; if (!data || !credentials) { console.error('获取临时密钥失败'); return; } callback({ TmpSecretId: credentials.tmpSecretId, TmpSecretKey: credentials.tmpSecretKey, SecurityToken: credentials.sessionToken, StartTime: data.startTime, ExpiredTime: data.expiredTime, }); }, fail: function (err) { console.error('请求临时密钥失败:', err); } }); }});/* 删除对象 */function deleteObject() { cos.deleteObject({ Bucket: 'examplebucket-1250000000', Region: 'ap-beijing', Key: 'picture.jpg', }, function (err, data) { if (err) { console.log('删除对象失败', err); } else { console.log('删除对象成功', data); console.log(err || data); } });}

十三、常见问题

你在使用过程中可能会碰到的一些常见问题，相关的解决办法可参见 小程序 SDK 常见问题。