对象存储 快速入门（JavaScript SDK）

一、相关资源

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

·SDK 示例 Demo 地址：XML JavaScript SDK Demo。

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

·SDK 常见问题请参见：JavaScript SDK 常见问题。

注意：说明：

注意：如果你在使用 XML 版本 SDK 时遇到函数或方法不存在等错误，请先将 XML 版本 SDK 升级到最新版再重试。如果你仍在使用 JSON 版本 SDK，请 升级到 XML JavaScript SDK。

二、环境配置与准备

2. 登录 对象存储控制台 ，创建存储桶。获取存储桶名称和 地域名称。

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

4. 配置 CORS 规则，AllowHeader 需配成*，ExposeHeaders 需要 ETag、Content-Length 以及其他 JS 需要读取的 header 字段。操作详情请参见 设置跨域访问 文档。

注意：说明：

三、安装 SDK

你可以通过以下方式安装 SDK：

四、方式一：script 引入

注意：说明：

注意：建议将 SDK 下载到本地后引入，选择 地址一 或 地址二 下载最新 cos-js-sdk-v5.min.js。

<!–src 为本地路径 根据自己项目目录结构来调整–><script src="../dist/cos-js-sdk-v5.min.js"></script>

在 script 标签引用 SDK 时，SDK 占用了全局变量名 COS，通过它的构造函数可以创建 SDK 实例。

五、方式二：Webpack 引入方式

通过 npm i cos-js-sdk-v5 –save 安装 SDK 依赖，支持 Webpack 打包的场景，你可以用 npm 引入作为模块，代码如下:

const COS = require('cos-js-sdk-v5');// 或import COS from 'cos-js-sdk-v5';

六、获取临时密钥

由于固定密钥放在前端会有安全风险，正式部署时我们推荐使用临时密钥的方式，实现过程为：前端首先请求服务端，服务端使用固定密钥调用 STS 服务申请临时密钥（具体内容请参见 临时密钥生成和使用指引 文档），然后返回临时密钥到前端使用。

注意：如果站点有登录态，这个获取临时密钥的接口，还需要加上登录态校验。

七、初始化 COS 实例

必须引入 SDK 完成初始化 cos 实例，才可以调用 sdk 的方法，例如 cos.uploadFile、cos.getObject。

SDK 内部需要通过密钥生成签名，密钥相关的初始化请参考以下示例。

单次临时密钥临时密钥回调永久密钥（仅测试）适用于单次上传动作，适合无需考虑临时密钥过期的场景，该密钥仅用于本次 COS 操作。import COS from 'cos-js-sdk-v5';// console.log(COS.version); sdk 版本需要不低于 1.8.3const cos = new COS({ SecretId: 'your_tmpSecretId', // sts服务下发的临时 secretId SecretKey: 'your_tmpSecretKey', // sts服务下发的临时 secretKey SecurityToken: 'your_sessionToken', // sts服务下发的临时 SessionToken StartTime: 1720770679403, // 建议传入服务端时间，可避免客户端时间不准导致的签名错误 ExpiredTime: 1720771991367, // 临时密钥过期时间 });上传文件实践：使用单次临时密钥上传文件，请参见 上传对象实践教程。采用回调的方式给 COS SDK 提供获取临时密钥的方法，SDK 会在首次和缓存的临时密钥快过期时使用该回调重新获取临时密钥。适用于全局初始化一个 cos 实例，方便进行上传文件的队列控制，暂停 、重启等操作。import COS from 'cos-js-sdk-v5';const cos = new COS({ 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，项目内全局使用：import COS from 'cos-js-sdk-v5';const cos = new COS({ // 其他配置项可参考下方 初始化配置项 // getAuthorization 必选参数 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 替换成你自己的后端服务 fetch(stsUrl) .then(response => response.json()) .then(data => { if (!data || !data.credentials) { return console.error('credentials invalid:\\n' + JSON.stringify(data, null, 2)) } // 检查credentials格式 const { credentials } = data; console.log(credentials); callback({ TmpSecretId: credentials.tmpSecretId, TmpSecretKey: credentials.tmpSecretKey, SecurityToken: credentials.sessionToken, // 建议返回服务器时间作为签名的开始时间，避免客户端本地时间偏差过大导致签名错误 StartTime: data.startTime, // 时间戳，单位秒，如：1580000000 ExpiredTime: data.expiredTime, // 时间戳，单位秒，如：1580000000 ScopeLimit: true, // 细粒度控制权限需要设为 true，会限制密钥只在相同请求时重复使用 }); }) .catch(error => { console.error('获取临时密钥失败', error); }); }});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），必须字段 Body: file, // 上传文件对象 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)你可以使用腾讯云的永久密钥来进行开发阶段的本地调试。由于该方式存在泄露密钥的风险，请务必在上线前替换为临时密钥的方式。import COS from 'cos-js-sdk-v5';// 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. 实例化时，传入 getAuthorization 回调，调用回调时返回临时密钥凭证，在临时密钥凭证过期后会再次调用该回调。

十、开启 Beacon 上报（可选）

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

注意：说明：

注意：腾讯灯塔只对 COS 侧的请求性能进行监控，不会上报业务侧数据。

若是想开启该功能，请先确保 SDK 版本升级到1.7.1及以上，然后在初始化中传入 BeaconReporter。

// 完整demo可参考：https://github.com/tencentyun/cos-js-sdk-v5/blob/master/demo/index.htmlconst Beacon = require('./lib/beacon_mp.min');new COS({ … BeaconReporter: Beacon,})

十一、使用方式

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

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

回调方式Promise 方式同步方式// 这里省略初始化过程和上传参数var cos = new COS({ … });cos.uploadFile({ … }, function(err, data) { if (err) { console.log('上传出错', err); } else { console.log('上传成功', data); }});// 这里省略初始化过程和上传参数var cos = new COS({ … });cos.uploadFile({ … }).then(data => { console.log('上传成功', data);}).catch(err => { console.log('上传出错', err);});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);}// JavaScript 的 async 和 await(使用时请注意浏览器兼容性)

十二、访问 COS 服务

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

查询对象列表上传对象下载对象删除对象/* vue 项目举例 *//* 新建一个 cos.js，导出 cos 实例 */import COS from 'cos-js-sdk-v5'; // 通过 npm 安装的 SDKconst cos = new COS({ SecretId: '你的 SecretId', SecretKey: '你的 SecretKey',});export default cos;/* 单页面里 page.vue */<template> <div> <button @click="getBucketFiles">查询目录a下的文件</button> <div v-if="fileList.length"> <h4>目录a下的文件列表：</h4> <ul> <li v-for="(file, i) in fileList" :key="i">{{ file.Key }}</li> </ul> </div> <p v-if="error" style="color: red;">{{ error }}</p> </div></template><script>import cos from '@/utils/cos';export default { data() { return { fileList: [], error: '' }; }, methods: { getBucketFiles() { cos.getBucket({ Bucket: 'examplebucket-1250000000', // 你的bucket Region: 'COS_REGION', // 你的地域（如ap-guangzhou） Prefix: 'a/' // 只查a目录下的文件 }, (err, data) => { if (err) { this.error = '查询失败：' + err.Message; this.fileList = []; } else { this.error = ''; this.fileList = data.Contents || []; // 展示文件路径（Key） } }); } }};</script>强烈推荐使用高级上传接口 uploadFile，自动针对小文件使用简单上传，大文件使用分块上传，性能更好。详情请参见 高级上传 文档。若使用临时密钥方式，需同时授权简单上传对象和分块上传的权限。请参见 授权指引。常见上传错误排查，请参见 常见问题。<template> <div> <input type="file" @change="handleUpload" /> </div></template><script>// 直接引入cos-js-sdk-v5（npm 安装）import COS from 'cos-js-sdk-v5';export default { methods: { handleUpload(e) { const file = e.target.files[0]; if (!file) return; // 直接在组件内初始化 COS 实例 const cos = new COS({ SecretId: '你的 SecretId', // 替换实际 SecretId SecretKey: '你的 SecretKey' // 替换实际 SecretKey }); // 调用上传方法 cos.uploadFile({ Bucket: 'examplebucket-1250000000', Region: 'ap-guangzhou', Key: `upload/${Date.now()}-${file.name}`, Body: file, SliceSize: 1024 * 1024 * 5 }, (err, data) => { err ? console.error('上传失败', err) : console.log('上传成功', data); e.target.value = ''; // 清空选择 }); } }};</script>浏览器里通过生成预签名 url 并触发浏览器下载的方式实现。<template> <div> <input type="text" v-model="fileKey" placeholder="输入文件Key（如a/1.jpg）" /> <button @click="getDownloadUrl">下载</button> </div></template><script>import COS from 'cos-js-sdk-v5';export default { data() { return { fileKey: '', cos: new COS({ SecretId: '你的 SecretId', SecretKey: '你的 SecretKey' }) }; }, methods: { getDownloadUrl() { if (!this.fileKey) return; this.cos.getObjectUrl({ Bucket: 'examplebucket-1250000000', Region: 'COS_REGION', Key: this.fileKey }, (err, data) => { if (err) return console.error(err); // 构建强制下载链接 const downloadUrl = data.Url + (data.Url.includes('?') ? '&' : '?') + 'response-content-disposition=attachment'; window.open(downloadUrl); }); } }};</script><template> <div> <input type="text" v-model="fileKey" placeholder="输入要删除的文件Key（如a/1.jpg）" /> <button @click="deleteFile">删除文件</button> </div></template><script>import COS from 'cos-js-sdk-v5';export default { data() { return { fileKey: '', cos: new COS({ SecretId: '你的 SecretId', SecretKey: '你的 SecretKey' }) }; }, methods: { deleteFile() { if (!this.fileKey.trim()) return; this.cos.deleteObject({ Bucket: 'examplebucket-1250000000', Region: 'COS_REGION', Key: this.fileKey.trim() }, (err, data) => { if (err) { console.error('删除失败', err); } else { console.log('删除成功', data); this.fileKey = ''; // 清空输入 } }); } }};</script>

十三、常见问题

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