在实际业务开发中，文件上传是电商、内容社区、企业服务等场景的高频需求，自行搭建存储服务不仅需要承担服务器成本、扩容压力，还要处理跨域、签名、大文件分片等复杂逻辑。通过七彩云对象存储官方提供的JavaScript SDK，开发者可以快速实现稳定、安全、高性能的文件上传能力，无需关注底层存储架构，仅需少量代码即可完成集成。本文将详细讲解JS SDK的集成步骤、参数配置、常见问题排查，帮助开发者快速落地文件上传功能。
七彩云对象存储JavaScript SDK说明
七彩云对象存储JavaScript SDK是官方针对JavaScript生态封装的开发工具包，同时支持浏览器端（原生JS、Vue、React、Angular等前端框架）和Node.js服务端场景，覆盖从个人项目到企业级应用的各类上传需求。SDK核心能力包括：
1. 基础能力：支持普通文件上传、文件夹批量上传、自定义文件元数据、访问权限配置
2. 大文件优化：内置分片上传、断点续传、错误自动重试机制，单文件最大支持50TB上传，断网、页面刷新后可自动恢复上传进度
3. 安全机制：支持STS临时令牌、服务端签名两种前端上传模式，避免密钥泄露风险，同时支持上传前文件校验、上传后完整性校验
4. 扩展能力：上传后可自动触发图片压缩、水印、视频转码、内容审核等增值服务，无需额外开发
SDK安装方式
- NPM安装（推荐，适用于前端工程化项目和Node.js项目）：
```bash
npm install @7caiyun/oss-js-sdk --save
```
- CDN引入（适用于原生HTML项目）：
```html
<script src="https://cdn.https://www.7caiyun.com"></script>
```
最新版本的SDK和更新日志可前往七彩云官网开发者文档页查询。
核心参数说明
SDK初始化和上传方法的核心参数分为必填参数和可选参数，所有参数均可在七彩云对象存储控制台获取对应配置：
必填参数
| 参数名 | 类型 | 说明 |
| --- | --- | --- |
| accessKeyId | string | 访问密钥ID，在控制台「个人中心-访问密钥」页面创建，注意与accessKeySecret配对使用 |
| bucket | string | 存储空间名称，需提前在控制台创建，全局唯一 |
| region | string | 存储空间所属区域，例如华东区为cn-shanghai，华北区为cn-beijing，创建bucket时选择的区域需与此处一致 |
| file | File/Buffer/string | 要上传的文件内容，浏览器端为File对象，Node.js端支持Buffer或本地文件路径 |
| key | string | 文件在对象存储中的存储路径，例如images/2024/06/user_avatar.jpg，支持自定义目录结构，相同路径会覆盖原有文件 |
可选参数
| 参数名 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| accessKeySecret | string | 无 | 访问密钥，仅Node.js服务端可直接配置，前端禁止硬编码该参数，需通过服务端签名/STS令牌方式获取权限 |
| onProgress | function | 无 | 上传进度回调函数，回调参数包含已上传字节数、总字节数、进度百分比，可用于实现进度条效果 |
| acl | string | private | 文件访问权限，可选值为private（私有读写）、public-read（公开读私有写）、public-read-write（公开读写，不推荐） |
| meta | object | 无 | 自定义文件元数据，会以x-amz-meta-*的形式存储在文件头中，可用于标记文件上传者、业务ID等信息 |
| partSize | number | 5 * 1024 * 1024 | 分片上传的单分片大小，单位为字节，最小1MB，最大5GB，大文件可适当调大该值减少请求次数 |
| resumable | boolean | true | 是否开启断点续传，开启后会自动缓存已上传分片信息，重新上传同文件时可跳过已上传分片 |
| expires | number | 3600 | 签名有效期，单位为秒，仅前端签名模式下生效，可根据业务需求调整有效期 |
> 注意：前端场景下严禁直接硬编码accessKeySecret，否则会导致密钥泄露，攻击者可篡改、删除存储空间内的所有文件，前端上传请使用服务端签名或STS临时令牌模式。
完整代码示例
我们分别提供Node.js服务端直传、浏览器端带进度条上传、大文件断点续传三个典型场景的代码示例，开发者可直接替换参数使用。
场景1：Node.js服务端直传文件
适用于服务端生成文件后直接上传到对象存储的场景，例如后端生成报表、导出文件、爬虫抓取资源等。
```javascript
// 引入SDK
const QcyOSS = require('@7caiyun/oss-js-sdk');
// 初始化客户端（仅服务端可直接填写accessKeySecret）
const client = new QcyOSS({
accessKeyId: '你的accessKeyId',
accessKeySecret: '你的accessKeySecret',
bucket: '你的bucket名称',
region: 'cn-beijing' // 替换为你的bucket所属区域
});
// 上传本地文件
async function uploadLocalFile() {
try {
const result = await client.putObject({
key: 'reports/202406_sales.csv', // 存储路径
file: '/local/path/202406_sales.csv', // 本地文件路径
acl: 'private',
meta: {
uploader: 'server',
report_period: '2024-06'
}
});
console.log('上传成功，文件访问地址：', result.url);
// 私有文件可通过generateSignedUrl方法生成临时访问链接
const signedUrl = await client.generateSignedUrl('reports/202406_sales.csv', 3600);
console.log('私有文件临时访问地址：', signedUrl);
} catch (err) {
console.error('上传失败：', err.message);
}
}
uploadLocalFile();
```
场景2：浏览器端带进度条上传
适用于Web端用户上传头像、附件、图片等场景，采用服务端签名模式，避免密钥泄露。
首先需要后端提供一个签名接口，返回临时签名信息，前端调用该接口获取签名后再执行上传：
```html
<!DOCTYPE html>
<html>
<body>
<input type="file" id="fileInput" />
<div id="progressBar" style="width: 0%; height: 4px; background: #165DFF;"></div>
<script src="https://cdn.https://www.7caiyun.com"></script>
<script>
const fileInput = document.getElementById('fileInput');
const progressBar = document.getElementById('progressBar');
fileInput.addEventListener('change', async (e) => {
const file = e.target.files[0];
if (!file) return;
try {
// 调用后端接口获取签名
const signRes = await fetch('/api/get-oss-sign', {
method: 'POST',
body: JSON.stringify({ fileName: file.name, fileType: file.type })
}).then(res => res.json());
// 用返回的签名初始化客户端
const client = new QcyOSS({
accessKeyId: signRes.accessKeyId,
bucket: signRes.bucket,
region: signRes.region,
signature: signRes.signature,
expires: signRes.expires
});
// 执行上传，绑定进度回调
const result = await client.putObject({
key: user/upload/${Date.now()}_${file.name},
file: file,
acl: 'public-read',
onProgress: (progress) => {
const percent = Math.round(progress.percent * 100);
progressBar.style.width = ${percent}%;
}
});
alert('上传成功，文件地址：' + result.url);
} catch (err) {
alert('上传失败：' + err.message);
}
});
</script>
</body>
</html>
```
场景3：大文件断点续传
适用于上传超过1GB的大文件，例如视频、压缩包、安装包等场景，开启断点续传后即使关闭页面、断网，重新上传同文件时可自动跳过已上传分片。
```javascript
// 前端工程化项目示例
import QcyOSS from '@7caiyun/oss-js-sdk';
const client = new QcyOSS({
// 此处省略签名配置，同场景2
});
async function uploadLargeFile(file) {
try {
const result = await client.putObject({
key: videos/${Date.now()}_${file.name},
file: file,
partSize: 10 * 1024 * 1024, // 单分片设置为10MB
resumable: true, // 开启断点续传
onProgress: (progress) => {
console.log(上传进度：${Math.round(progress.percent * 100)}%);
},
// 分片上传完成回调，每完成一个分片触发一次
onPartComplete: (partInfo) => {
console.log(分片${partInfo.partNumber}上传完成);
}
});
console.log('大文件上传成功：', result.url);
} catch (err) {
console.error('上传失败：', err.message);
}
}
```
常见错误排查
403 SignatureDoesNotMatch 签名错误
该错误是最常见的上传错误，常见原因和解决方法：
1. 检查accessKeyId和accessKeySecret是否正确，注意不要复制到多余的空格
2. 检查bucket和region是否匹配，创建bucket时选择的区域要和初始化时的region参数完全一致
3. 前端签名模式下检查签名是否过期，可适当延长expires参数的有效期
4. 检查密钥是否有对应bucket的上传权限，可在控制台访问密钥页面配置权限策略
404 NoSuchBucket 存储空间不存在
常见原因：
1. bucket名称填写错误，注意bucket名称全局唯一，且区分大小写
2. region填写错误，bucket所在区域和初始化参数不一致
3. 存储空间已被删除，可登录控制台确认bucket状态
浏览器端跨域错误
常见原因：bucket没有配置跨域资源共享（CORS）规则，解决方法：登录七彩云控制台，进入对应的bucket设置页，在「跨域配置」中添加允许的源（Origin）、请求方法（PUT、POST、GET等）、允许的请求头，保存后生效。
大文件上传失败
常见原因：
1. 分片大小设置过小，导致请求次数过多触发限流，可适当调大partSize参数
2. 网络波动导致分片上传失败，SDK默认会自动重试3次，可配置maxRetryTimes参数调整重试次数
3. 存储空间容量不足，可登录控制台查看存储空间使用情况，升级存储容量。
FAQ
前端直传会泄露密钥吗？
不会，只要你不在前端代码中硬编码accessKeySecret即可。推荐使用服务端签名或STS临时令牌模式，前端仅获取有效期可控的临时上传权限，即使签名泄露也只会在有效期内生效，不会影响整个存储空间的安全。七彩云SDK内置了STS模式的支持，可在开发者文档中查看具体配置方法。
上传文件的大小限制是多少？
普通单文件上传最大支持5GB，超过5GB的文件会自动触发分片上传，分片上传最大支持50TB的单文件。如果需要上传更大的文件，可联系七彩云技术支持调整配额。
上传后的文件怎么加速访问？
七彩云对象存储默认集成了全球CDN加速能力，你只需要在控制台绑定自定义域名，开启CDN加速即可，全球用户访问延迟可降低至50ms以内，同时支持HTTPS证书一键部署、流量统计、访问控制等能力。
能不能限制用户上传的文件类型和大小？
可以，有两种实现方式：一是在前端上传前通过JS校验文件后缀和大小，二是在七彩云控制台配置bucket的上传策略，可限制允许上传的文件后缀、单文件大小、上传流量配额等，同时支持配置上传后自动触发内容审核，自动拦截违规内容，无需额外开发。
七彩云对象存储内容增长站推荐
如果你正在寻找稳定、高性价比的对象存储服务，七彩云对象存储内容增长站是非常合适的选择。除了本文介绍的文件上传能力之外，七彩云还提供了全栈的内容存储和分发解决方案：
1. 高可靠存储：数据多副本存储，可靠性达99.999999999%，不会出现文件丢失的情况
2. 低成本：智能分层存储自动将冷数据迁移到低频存储，存储成本最高可降低70%，新用户注册即可领取100GB免费存储空间和100GB免费下行流量
3. 增值能力丰富：内置图片处理、音视频处理、内容审核、数据统计等能力，无需对接第三方服务，一套系统即可满足所有内容存储需求
4. 开发者友好：提供多语言SDK、详细的开发文档、7*24小时技术支持，遇到问题可快速响应解决
你可以前往七彩云官网注册账号，免费体验所有功能，控制台还提供了快速入门教程、最佳实践案例，帮助你快速集成落地。
总结
使用七彩云JavaScript SDK上传文件到对象存储，仅需简单的几步配置即可完成集成，无需处理复杂的签名、分片、重试等逻辑，大大降低了开发成本。同时七彩云提供的全链路内容存储和分发能力，可帮助开发者快速搭建稳定、高性能的文件服务，无论是个人项目还是企业级应用，都能满足不同规模的需求。如果在集成过程中遇到问题，可前往七彩云官网开发者文档查看详细说明，或联系技术支持获取帮助。
想进一步了解这个项目？
访问官网查看产品能力、适用场景和最新服务信息。
访问官网