Spring Boot + Vue2 实现腾讯云 COS 文件上传：从零搭建分片上传系统
目录
一、项目目标
二、腾讯云 COS 基本配置
1. 创建存储桶
2. 获取 API 密钥
3. 设置跨域规则（CORS）
三、后端（Spring Boot）实现
1. 依赖配置
2. 配置腾讯云 COS（application.yml）
3. 初始化 COS 客户端
4. 文件上传接口
（1）普通上传
（2）分片上传接口
① 初始化分片上传
② 上传分片
③ 合并分片
四、前端（Vue2）实现
1. 安装依赖
2. 分片上传逻辑
五、注意事项与优化
1. 分片大小限制
2. 并发上传优化
3. 断点续传支持
4. 安全性增强
六、总结
一、项目目标
实现基于腾讯云 COS 的 大文件分片上传 和 普通文件上传 功能，前后端分离架构，采用 Vue2 + Spring Boot + YML 配置方式，并覆盖以下注意事项：
- 分片上传大小限制
- 并发上传优化
- 断点续传支持
- 安全性增强（避免暴露密钥）
- 跨域规则配置（CORS）
二、腾讯云 COS 基本配置
1. 创建存储桶
登录腾讯云控制台 → 对象存储 COS → 创建存储桶：
- 存储桶名称：
your-bucket-name-1250000000 - 地域：
ap-beijing（根据需求选择） - 权限设置：私有读写
2. 获取 API 密钥
前往 API 密钥管理 页面，创建或使用已有 SecretId/SecretKey。
✅ 安全建议：前端禁止直接使用 SecretId/SecretKey，应通过后端代理或使用 STS 临时密钥。
3. 设置跨域规则（CORS）
前往 权限管理 → 跨域规则，添加以下规则：
{"allowedOrigin": ["*"],"allowedMethod": ["GET", "POST", "PUT", "HEAD"],"allowedHeader": ["*"],"exposeHeader": [],"maxAgeSeconds": 3000
}三、后端（Spring Boot）实现
1. 依赖配置
<dependencies><!-- Spring Boot Web --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><!-- 腾讯云 COS SDK --><dependency><groupId>com.qcloud</groupId><artifactId>cos_api</artifactId><version>5.2.4</version></dependency><!-- 工具类 --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter</artifactId></dependency>
</dependencies>2. 配置腾讯云 COS（application.yml）
tencent:cos:secret-id: YOUR_SECRET_IDsecret-key: YOUR_SECRET_KEYregion: ap-beijingbucket-name: your-bucket-name-12500000003. 初始化 COS 客户端
import com.qcloud.cos.COSClient;
import com.qcloud.cos.auth.BasicCOSCredentials;
import com.qcloud.cos.auth.COSCredentials;
import com.qcloud.cos.region.Region;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;@Configuration
public class CosConfig {@Value("${tencent.cos.secret-id}")private String secretId;@Value("${tencent.cos.secret-key}")private String secretKey;@Value("${tencent.cos.region}")private String region;@Beanpublic COSClient cosClient() {COSCredentials cred = new BasicCOSCredentials(secretId, secretKey);Region cosRegion = new Region(region);return new COSClient(cred, cosRegion);}
}4. 文件上传接口
（1）普通上传
import com.qcloud.cos.COSClient;
import com.qcloud.cos.model.PutObjectRequest;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;import java.io.InputStream;
import java.util.UUID;@RestController
@RequestMapping("/api/upload")
public class UploadController {@Autowiredprivate COSClient cosClient;@Value("${tencent.cos.bucket-name}")private String bucketName;@PostMapping("/simple")public String simpleUpload(@RequestParam("file") MultipartFile file) {try {String remoteFileName = "uploads/" + UUID.randomUUID().toString() + "-" + file.getOriginalFilename();InputStream inputStream = file.getInputStream();PutObjectRequest request = new PutObjectRequest(bucketName, remoteFileName, inputStream, null);cosClient.putObject(request);return "https://" + bucketName + ".cos." + cosClient.getClientConfig().getRegion().getName() + ".myqcloud.com/" + remoteFileName;} catch (Exception e) {return "上传失败: " + e.getMessage();}}
}（2）分片上传接口
① 初始化分片上传
@PostMapping("/init")
public String initMultipartUpload(@RequestParam String fileName) {try {InitiateMultipartUploadRequest request = new InitiateMultipartUploadRequest(bucketName, fileName);return cosClient.initiateMultipartUpload(request).getUploadId();} catch (Exception e) {return "初始化失败: " + e.getMessage();}
}② 上传分片
@PostMapping("/part")
public String uploadPart(@RequestParam("file") MultipartFile file,@RequestParam("uploadId") String uploadId,@RequestParam("partNumber") int partNumber,@RequestParam("fileName") String fileName) {try {UploadPartRequest request = new UploadPartRequest().withBucketName(bucketName).withKey(fileName).withUploadId(uploadId).withPartNumber(partNumber).withInputStream(file.getInputStream()).withPartSize(file.getSize());return cosClient.uploadPart(request).getETag(); // 返回 ETag} catch (Exception e) {return "分片上传失败: " + e.getMessage();}
}③ 合并分片
@PostMapping("/complete")
public String completeMultipartUpload(@RequestParam("fileName") String fileName,@RequestParam("uploadId") String uploadId,@RequestParam("partETags") List<String> partETags) {try {List<PartETag> partETagList = partETags.stream().map(etag -> new PartETag(partETags.indexOf(etag) + 1, etag)).toList();CompleteMultipartUploadRequest request = new CompleteMultipartUploadRequest(bucketName, fileName, uploadId, partETagList);cosClient.completeMultipartUpload(request);return "https://" + bucketName + ".cos." + cosClient.getClientConfig().getRegion().getName() + ".myqcloud.com/" + fileName;} catch (Exception e) {return "合并失败: " + e.getMessage();}
}四、前端（Vue2）实现
1. 安装依赖
npm install axios2. 分片上传逻辑
<template><div><input type="file" @change="handleFileChange" /><button @click="uploadFile">上传</button><div>上传进度: {{ progress }}%</div></div>
</template><script>
import axios from 'axios';export default {data() {return {file: null,uploadId: '',chunkSize: 5 * 1024 * 1024, // 5MBprogress: 0,uploadedChunks: [], // 已上传的分片索引};},methods: {handleFileChange(event) {this.file = event.target.files[0];this.uploadedChunks = [];this.progress = 0;},async uploadFile() {if (!this.file) {alert("请选择文件");return;}// 1. 初始化分片上传const initRes = await axios.post('/api/upload/init', {fileName: this.file.name,});this.uploadId = initRes.data;// 2. 并发上传分片const totalChunks = Math.ceil(this.file.size / this.chunkSize);const promises = [];for (let i = 0; i < totalChunks; i++) {const start = i * this.chunkSize;const end = Math.min(start + this.chunkSize, this.file.size);if (this.uploadedChunks.includes(i)) continue; // 跳过已上传分片const chunk = this.file.slice(start, end);const formData = new FormData();formData.append('file', chunk);formData.append('uploadId', this.uploadId);formData.append('partNumber', i + 1);formData.append('fileName', this.file.name);const promise = axios.post('/api/upload/part', formData, {onUploadProgress: (progressEvent) => {const percent = Math.round(((this.uploadedChunks.length * 100) / totalChunks) +((progressEvent.loaded / progressEvent.total) * 100 / totalChunks));this.progress = percent;},});promises.push(promise.then(() => {this.uploadedChunks.push(i); // 标记为已上传}));}// 并发上传await Promise.all(promises);// 3. 合并分片const completeRes = await axios.post('/api/upload/complete', {fileName: this.file.name,uploadId: this.uploadId,partETags: [], // 后端应返回每个分片的 ETag});alert("上传成功: " + completeRes.data);},},
};
</script>五、注意事项与优化
1. 分片大小限制
- 腾讯云要求 单个分片最小 1MB，最大 5GB。
- 推荐设置
chunkSize = 5 * 1024 * 1024（5MB）。
2. 并发上传优化
- 使用
Promise.all实现并发上传，提升上传效率。 - 可设置最大并发数，避免过多请求导致服务器压力过大。
3. 断点续传支持
- 通过
this.uploadedChunks记录已上传分片索引。 - 重启上传时跳过已上传部分，实现断点续传。
4. 安全性增强
- 禁止前端暴露 SecretId/SecretKey。
- 建议使用 STS 临时密钥 或 后端代理上传。
- 后端可封装上传逻辑，前端仅调用后端接口上传文件。
- 使用腾讯云 STS 获取临时密钥，设置访问权限和有效期。
六、总结
本教程完整实现了基于 Spring Boot + Vue2 的腾讯云 COS 文件上传功能，支持：
- 普通上传
- 大文件分片上传（支持并发、断点续传）
- 安全性增强（密钥不暴露）
- 跨域规则配置（CORS）
可根据实际业务需求进一步扩展，如添加上传进度持久化、上传失败重试机制等。