1. 方案选型与整体思路拆解1.1 为什么最终选了前端直传先聊一个很多朋友都会纠结的问题文件上传到底该走“后端中转”还是“前端直传”我最早做这个项目时第一版用的是后端中转——前端把文件POST给后端接口后端再转存到对象存储。这样做的优点是对前端友好代码写起来简单甚至后端框架自带的上传逻辑改改就能用。但项目一上线问题就来了大文件上传时服务器带宽成了瓶颈上传一个几十MB的视频后端服务器的CPU和内存波动非常明显好几个并发上来之后接口响应都开始变慢严重的时候把正常业务请求也拖垮了。后来我换成了“前端直传腾讯云COS”的方案浏览器端拿到临时密钥后把文件直接传往腾讯云的对象存储桶整个过程不经过自己的业务服务器。好处是显而易见的带宽消耗被分摊到云厂商的CDN和存储节点上自己的服务器只管签发一次临时密钥实际传输压力几乎为零。而且腾讯云COS在中国大陆区域的传输速度本身就有保障大文件上传体验比走业务服务器中转好很多。这个方案非常适合有较多图片、视频、附件上传需求的Web应用尤其是后台管理系统这类常见场景。我调研过市面上几种方案一是纯后端上传适合文件类型单一、并发量低、业务对文件安全性要求极高的场景二是前端直传加上服务端签名适合大部分中大型业务既不需要暴露长期密钥又不会给服务器带来太大压力三是前端直传、后端回调校验适合需要强一致性的场景。考虑到项目使用的是VueElement-UI技术栈我最终采用了第二种也就是基于Element-UI Upload组件的自定义上传能力配合axios签发临时密钥再用腾讯云官方SDK完成文件上传。1.2 整体链路是怎么设计的整个上传链路由三个角色构成浏览器端、业务后端、腾讯云COS。业务后端负责提供临时密钥和必要的签名信息腾讯云COS负责实际存储浏览器端则是整个流程的组织者。具体的执行顺序是这样的前端用户选择文件后先向自己的业务后端请求STS临时密钥Security Token Service后端校验用户登录态和上传权限后调用腾讯云的STS接口签发临时凭证返回给前端。前端拿到AccessKeyId、SecretAccessKey、SessionToken和过期时间后初始化腾讯云COS SDK再把文件切片并逐个上传到目标存储桶。整个过程用户感知不到中间步骤体验和一个普通的上传表单完全一致但底层的数据流已经不经过自己的服务器了。这里有一个关键点临时密钥是有时效性的默认情况下可能只有几十分钟到几小时。如果用户上传的文件非常多、耗时很长密钥过期后上传就会失败。所以我在设计时加了一个密钥缓存和刷新机制第一次请求后把临时密钥存在前端快要过期前自动重新向后端申请保证长时间连续上传不会中断。这个细节在实际项目中非常重要尤其是用户一次批量上传几十张图片的时候。2. 项目准备与核心配置2.1 存储桶与跨域配置的坑在动手写代码之前有两项配置必须在腾讯云控制台提前准备一个是创建存储桶另一个是配置CORS跨域规则。很多新手第一次做直传时会卡在报错上其实问题往往不在代码而是跨域规则没配好。创建存储桶时我建议把读写权限设置为“私有读写”。有的同学会图省事直接选“公有读私有写”这样文件可以通过固定链接被所有人访问但对于用户上传的头像、证件照这类数据来说并不合适。私有读写配合后端签名URL才能做到安全可控。CORS跨域规则是重中之重。浏览器端直传COS本质上就是浏览器向COS发起的AJAX请求必然受到同源策略限制。如果控制台里没有配置允许跨域的规则前端会直接报“CORS policy: No Access-Control-Allow-Origin header”这类错误。配置时需要注意几个点AllowedOrigin要写你实际部署的前端域名开发环境可能是localhost千万别漏了AllowedMethod至少要包含PUT、POST、GET、HEAD、DELETEAllowedHeader建议填*否则SDK上传时自定义的头部信息会被浏览器拦截ExposeHeader建议填ETag、x-cos-request-id等方便前端定位问题。2.2 临时密钥签名链路临时密钥的正确获取方式是前端直传方案的重点。腾讯云官方推荐的做法是前端调用自己的后端接口后端再用腾讯云的STS SDK去换取临时密钥。为什么要绕这一道因为长期密钥SecretId和SecretSecretKey是绝对不能暴露在前端代码里的一旦暴露任何人都可以拿着它操作你的整个COS账号轻则产生大量流量费用重则数据被删。而直接放在前端代码里的密钥等于把大门钥匙交给所有路过的人。后端签发的临时密钥包含四个核心字段credentials.tmpSecretId、credentials.tmpSecretKey、credentials.sessionToken和expiredTime。前三个字段会交给前端SDK初始化使用expiredTime是用来判断密钥是否需要刷新的。字段名在不同SDK版本里可能略有差异但整体结构一致。有的项目为了省事会让前端直接拼接COS API的签名算法自己用crypto-js计算签名。这个路子不是不行但计算签名要处理Host、Headers、URL参数等一系列细节一旦某个地方编码格式不对排查起来特别费劲。而且密钥还是得找个地方存。相比之下用官方SDK配合STS临时密钥既安全又省心是我实测下来最稳的方案。3. 核心代码实现与关键参数3.1 Upload组件侧的模板与状态管理Element-UI的Upload组件默认的上传方式是把自己的action指向一个后端接口靠组件内部封装的XHR去发请求。这种方式在走“后端中转”时确实简单但我们要改成前端直传COS就没有现成的后端接口可以指向了。好在Upload组件提供了http-request这个配置项可以让我们完全接管上传逻辑。我的模板结构大致是这样写的template div classupload-wrapper el-upload refuploadRef action# :show-file-listfalse :before-uploadbeforeUpload :http-requesthandleHttpRequest :on-successhandleSuccess :on-errorhandleError :on-progresshandleProgress :on-removehandleRemove :limit10 :on-exceedhandleExceed acceptimage/* multiple el-button typeprimary选择图片/el-button /el-upload div classfile-list div v-forfile in fileList :keyfile.uid classfile-item span{{ file.name }}/span el-progress :percentagefile.percent / /div /div /div /template有几个细节值得注意第一action属性传一个#占位因为http-request接管之后它会失效但如果不填组件内部校验会不通过。第二show-file-list我设置成了false因为默认的组件文件列表在直传场景下不好控制状态尤其牵扯到分片上传时组件内置的进度条和实际的分片进度很难对齐。所以我选择自己维护一个fileList数组完全掌控每张照片的状态。第三limit和on-exceed组合使用可以控制上传数量上限acceptimage/*用来限定文件类型但注意它只是弹窗筛选不是安全校验后端或COS侧最好再做一次校验。3.2 基于http-request接管上传流程http-request是Upload组件暴露给我们的一个“完全接管”的入口它接收一个配置对象包含file、onSuccess、onError、onProgress等信息。这个设计非常巧妙等于把组件的状态回调机制完整地交给我们自己控制。我的核心上传函数是这样组织的import COS from cos-js-sdk-v5; let cosInstance null; let taskMap new Map(); // 用于存储任务Id便于取消 // 向后端获取临时密钥 async function getCOSCredentials() { const response await axios.get(/api/cos/sts); const { tmpSecretId, tmpSecretKey, sessionToken, expiredTime } response.data; return { tmpSecretId, tmpSecretKey, sessionToken, expiredTime }; } // 初始化或复用COS实例 async function getCOSInstance() { if (cosInstance) return cosInstance; const credentials await getCOSCredentials(); if (!credentials.tmpSecretId || !credentials.tmpSecretKey || !credentials.sessionToken) { throw new Error(获取临时密钥失败); } cosInstance new COS({ getAuthorization: (options, callback) { // 每次请求前检查密钥是否临近过期如果过期则重新获取 const now Math.floor(Date.now() / 1000); if (credentials.expiredTime - now 60) { getCOSCredentials().then(newCredentials { Object.assign(credentials, newCredentials); callback({ TmpSecretId: credentials.tmpSecretId, TmpSecretKey: credentials.tmpSecretKey, SecurityToken: credentials.sessionToken, StartTime: now, ExpiredTime: credentials.expiredTime }); }).catch(error callback(error)); } else { callback({ TmpSecretId: credentials.tmpSecretId, TmpSecretKey: credentials.tmpSecretKey, SecurityToken: credentials.sessionToken, StartTime: now, ExpiredTime: credentials.expiredTime }); } } }); return cosInstance; }这里有个容易踩坑的地方getAuthorization不是只调用一次的。COS SDK在每次发请求前都会调它一次包括初始化、分片上传的每一个分片、完成合并请求等。如果每次都去请求后端拿新的密钥会产生大量不必要的请求。所以我做了一个简单的判断如果密钥剩余时间还超过60秒就直接复用缓存否则才重新获取。这个60秒的提前量是经验值给SDK留出网络波动和时钟偏差的空间。接下来是handleHttpRequest的实现。Upload组件传给它的参数中onProgress等回调是组件内置的但我们自己接管后必须手动调用它们才能让组件的状态机制继续工作。我的做法是让handleHttpRequest返回一个带abort()方法的对象这样组件在移除文件或取消上传时能主动中断我们正在进行的COS上传任务。async function handleHttpRequest({ file, onProgress, onSuccess, onError }) { const fileName file.name; const ext fileName.split(.).pop().toLowerCase(); const key uploads/${Date.now()}-${Math.floor(Math.random() * 10000)}.${ext}; const COS_OPTIONS { Bucket: your-bucket-name-1250000000, Region: ap-guangzhou, Key: key, Body: file, SliceSize: 1024 * 1024 * 5, // 大于5MB的文件自动分片 }; try { const instance await getCOSInstance(); const taskId instance.uploadFile({ ...COS_OPTIONS, onProgress: (data) { const percent Math.floor(data.percent * 100); onProgress({ percent }); }, onSuccess: (data) { const url https://your-bucket-name-1250000000.cos.ap-guangzhou.myqcloud.com/${key}; onSuccess({ url, key, data }); }, onError: (error) { onError(error); } }); taskMap.set(file.uid, taskId); return { abort() { instance.cancelTask(taskId); taskMap.delete(file.uid); } }; } catch (error) { onError(error); } }Key的设计需要多花点心思。我直接用uploads/前缀加时间戳和随机数拼接这样可以避免中文文件名在URL里出现编码问题也减少同名文件互相覆盖的风险。如果你有按用户ID分目录的需求也可以在Key里加上用户的标识比如uploads/user_12345/xxxxx.jpg这样管理起来更清晰。3.3 进度条、文件状态与取消机制自己接管上传之后进度条和文件状态必须同步维护。在我接手这个项目时发现一个经典问题Element-UI内置的el-upload文件列表有自己的status和percentage字段但直传COS时分片上传的进度是COS SDK回调的两者很容易对不上。这时候有两种选择一种是把show-file-list保持为true然后在onProgress回调里手动更新file.percentage字段另一种是像我的模板里那样完全隐藏内置列表自己渲染一个。我选择了后者原因有两个。第一内置列表的样式定制空间很小加上缩略图、重试按钮、取消按钮都要额外处理不如自己写灵活。第二直传场景下我们需要展示的进度粒度更细——单个文件切片数、整体上传进度、以及失败后的重试入口这些都是自定义列表更好做。我的fileList数据项设计为// fileList里的每一项 { uid: 唯一标识, name: example.jpg, status: uploading | success | error, percent: 0, url: , }onProgress回调更新percent和statusonSuccess更新url和statusonError只更新status。重试操作就是再次调用handleHttpRequest里那一整套逻辑。这里有个小技巧不要把COS的临时密钥和实例做成全局持久化的因为密钥会过期。我实际写代码时会在组件beforeDestroy钩子里调用instance.cancelAll()来清理未完成的任务防止页面销毁后COS的回调还在触发Vue组件更新导致控制台报错。3.4 后端STS接口的简单示例虽然这篇文章主要讲前端但后端的STS接口是整个链路能跑通的前提。我写了一个简化的Node.js示例核心原理是使用腾讯云STS SDK用自己服务端配置的永久密钥去换一个临时密钥。const STS require(qcloud-cos-sts); const config { SecretId: process.env.TENCENT_SECRET_ID, SecretKey: process.env.TENCENT_SECRET_KEY, DurationSeconds: 7200, Bucket: your-bucket-name-1250000000, Region: ap-guangzhou, }; router.get(/api/cos/sts, async (req, res) { // 这里一定要先校验用户登录态再执行以下逻辑 const shortBucketName config.Bucket.slice(0, config.Bucket.lastIndexOf(-)); const policy { version: 2.0, statement: [{ action: [ cos:PutObject, cos:PostObject, cos:UploadPart, cos:CompleteMultipartUpload, cos:AbortMultipartUpload, ], effect: allow, resource: [ qcs::cos:${config.Region}:uid/1250000000:${shortBucketName}-1250000000/uploads/*, ], condition: { ip_equal: { qcs:ip: req.ip }, }, }], }; const result await STS.getCredential({ secretId: config.SecretId, secretKey: config.SecretKey, policy, durationSeconds: config.DurationSeconds, }); res.json(result.credentials); });策略里的resource限制了临时密钥只能操作uploads/目录下的对象并且限定来源IP是当前请求的IP地址。这是安全上的一道双保险。限制目录的好处是即使临时密钥被截获攻击者也不能遍历或操作整个桶里的其他文件。我在线上的COS桶里除了uploads/还存了静态资源如果不加这条目录限制风险会大很多。4. 常见问题与排查技巧实录4.1 跨域报错怎么定位我见过最多的问题就是跨域报错。现象是控制台报Access to XMLHttpRequest at https://xxx.cos.ap-guangzhou.myqcloud.com/... from origin http://localhost:8080 has been blocked by CORS policy。很多朋友一看到这个就蒙了其实定位思路很清晰先确认COS桶的CORS配置里有没有包含你当前的前端域名再确认请求方法是不是都在AllowedMethod里最后确认AllowedHeader有没有设成*。有一个很容易忽略的坑CORS配置修改后浏览器和COS的边缘节点会有缓存。也就是说你在控制台改完规则立刻回前端刷新页面测试发现还是报同样的错这不一定是没改成功可能是缓存还没过期。建议等一两分钟再测或者用无痕窗口验证。我几次“改完无效”的假象最后都是缓存在作怪。4.2 上传成功但组件状态异常这个问题非常典型。表现是COS里文件已经传上去了但页面的文件状态一直停留在“上传中”或者进度条卡在99%不动。排查下来大部分原因是onProgress回调里percent字段的取法不对。COS SDK的onProgress回调返回的对象里percent是一个0到100的整数也可能带上小数而Element-UI的el-progress组件期望的是0到100的数字。有的版本里可能返回1.0这类浮点数有的返回0.123这种比例值如果你不统一单位就会出现“瞬间跳到100%后又回退”的情况。我习惯在回调里强制做一次Math.floor(data.percent)确保单位统一。另一个状态异常的来源是http-request没有正确返回abort方法。Element-UI的Upload组件在移除文件时会去调用fileList对应项的XHR对象的abort方法但自定义上传时我们并没有真正的XHR对象组件只能调用我们返回的对象上的abort。如果不返回这个方法移除文件时组件会报错或者干脆没反应。4.3 签名过期与并发问题签名过期是另一个高频坑。最典型的场景是用户打开上传页面超过半小时才开始选文件或者批量上传大文件时传了一半密钥过期了。前者可以通过在getAuthorization里检查过期时间解决后者则更麻烦因为密钥的刷新时机正好落在分片上传的中间——某个分片用旧密钥在传下一个分片已经开始请求新密钥了这种并发状态下偶尔会出现400或403异常。我的解决方案是给密钥刷新加一个互斥锁。用简单的Promise链让并发请求等待同一个刷新操作完成避免多个分片同时触发多次STS请求。具体实现可以是let credentialPromise null; function requestCredentials() { if (!credentialPromise) { credentialPromise getCOSCredentials() .then(data { credentialPromise null; return data; }) .catch(error { credentialPromise null; throw error; }); } return credentialPromise; }这样即使几十个分片同时需要新密钥也只有一个真正的STS请求在飞其余的全部复用同一个Promise的返回值。这个模式不只是COS上传可以用任何前端“一次性初始化”的异步资源比如SDK加载、token获取都适用。4.4 分片大小与并发参数的选择SliceSize参数决定了上传时是否启用分片以及分片的大小。我实测下来的经验是对于普通图片把SliceSize设为5MB即可对于几百MB的视频分片大小可以提高到10MB甚至20MB减少分片数量降低合并请求的压力。分片太小会导致发起大量HTTP请求性能反而下降太大则失去分片上传的断点续传优势。COS SDK内部对分片上传的并发数也有默认值通常不需要手动调。但如果你的用户普遍网络带宽很高可以适当调高并发数来加速上传如果网络质量不稳定反而应该降低并发数减少单个分片失败导致整个上传失败的概率。我一般是先按默认值跑然后在监控后台观察上传耗时和失败率再微调。5. 其他注意事项与补充5.1 完整的文件校验流程直传模式下前端的文件校验不能只靠accept属性。我在beforeUpload里会做以下检查文件大小是否超过限制、文件类型是否符合白名单、文件名后缀是否在允许列表中。COS SDK虽然会做服务端的校验但如果前端能把明显不合法的请求拦截下来既减少无效上传也避免用户被莫名其妙的错误提示困扰。function beforeUpload(file) { const MAX_SIZE 20 * 1024 * 1024; // 20MB const WHITE_LIST [image/jpeg, image/png, image/gif, image/webp]; if (file.size MAX_SIZE) { this.$message.error(文件大小不能超过20MB); return false; } if (WHITE_LIST.indexOf(file.type) -1) { this.$message.error(仅支持jpg、png、gif、webp格式); return false; } return true; }注意file.type在部分浏览器里可能为空字符串尤其是某些压缩包或者特殊格式图片。所以不能完全依赖MIME类型要同时保留后缀名的判断逻辑两种校验双保险。5.2 隐私与安全的几个小建议前端直传COS虽然把存储压力转移到了云端但安全问题不能忽视。除了前面提到的STS临时密钥、目录权限限定之外我还建议在COS控制台开启防盗链限制Referer来源域名防止他人盗用图片链接。另外私有读写的桶要配合生成临时URL供前端显示缩略图这时候可以用COS SDK的getObjectUrl方法生成带签名、带有效期的访问地址。还有一个经常被忽略的点上传完成后业务后端最好通过COS的事件通知或回调接口做二次确认。也就是说前端告诉后端“我传成功了”后端可以再调COS API验证这个文件确实存在并且校验它的大小、类型是否和预期一致。这样能防止前端伪造上传成功的信息在安全级别要求高的业务里很有必要。5.3 后续扩展方向这个方案跑通之后可以扩展的点其实很多。比如结合COS的图片处理API在上传完成后生成不同尺寸的缩略图或者把上传记录写入数据库做成一个完整的“附件中心”再或者加上相似度检查、图片审核功能。对我自己来说最实用的是把上传回调里生成的URL直接回填到表单数据里整个流程就顺畅闭环了。最后再分享一个我调试时觉得特别好用的技巧在开发环境下可以用Vue的mixin全局注入一个调试开关当?debugcos出现在URL里时把COS SDK每次请求的requestId、statusCode、taskId都打印到控制台。这样在线上定位问题的时候只要让用户带上这个参数访问就能拿到完整的上传链路日志比自己猜要高效得多。这个习惯帮我省了无数次远程排查的时间也算是一个值得留存的小工具。
1. 方案选型与整体思路拆解1.1 为什么最终选了前端直传先聊一个很多朋友都会纠结的问题文件上传到底该走“后端中转”还是“前端直传”我最早做这个项目时第一版用的是后端中转——前端把文件POST给后端接口后端再转存到对象存储。这样做的优点是对前端友好代码写起来简单甚至后端框架自带的上传逻辑改改就能用。但项目一上线问题就来了大文件上传时服务器带宽成了瓶颈上传一个几十MB的视频后端服务器的CPU和内存波动非常明显好几个并发上来之后接口响应都开始变慢严重的时候把正常业务请求也拖垮了。后来我换成了“前端直传腾讯云COS”的方案浏览器端拿到临时密钥后把文件直接传往腾讯云的对象存储桶整个过程不经过自己的业务服务器。好处是显而易见的带宽消耗被分摊到云厂商的CDN和存储节点上自己的服务器只管签发一次临时密钥实际传输压力几乎为零。而且腾讯云COS在中国大陆区域的传输速度本身就有保障大文件上传体验比走业务服务器中转好很多。这个方案非常适合有较多图片、视频、附件上传需求的Web应用尤其是后台管理系统这类常见场景。我调研过市面上几种方案一是纯后端上传适合文件类型单一、并发量低、业务对文件安全性要求极高的场景二是前端直传加上服务端签名适合大部分中大型业务既不需要暴露长期密钥又不会给服务器带来太大压力三是前端直传、后端回调校验适合需要强一致性的场景。考虑到项目使用的是VueElement-UI技术栈我最终采用了第二种也就是基于Element-UI Upload组件的自定义上传能力配合axios签发临时密钥再用腾讯云官方SDK完成文件上传。1.2 整体链路是怎么设计的整个上传链路由三个角色构成浏览器端、业务后端、腾讯云COS。业务后端负责提供临时密钥和必要的签名信息腾讯云COS负责实际存储浏览器端则是整个流程的组织者。具体的执行顺序是这样的前端用户选择文件后先向自己的业务后端请求STS临时密钥Security Token Service后端校验用户登录态和上传权限后调用腾讯云的STS接口签发临时凭证返回给前端。前端拿到AccessKeyId、SecretAccessKey、SessionToken和过期时间后初始化腾讯云COS SDK再把文件切片并逐个上传到目标存储桶。整个过程用户感知不到中间步骤体验和一个普通的上传表单完全一致但底层的数据流已经不经过自己的服务器了。这里有一个关键点临时密钥是有时效性的默认情况下可能只有几十分钟到几小时。如果用户上传的文件非常多、耗时很长密钥过期后上传就会失败。所以我在设计时加了一个密钥缓存和刷新机制第一次请求后把临时密钥存在前端快要过期前自动重新向后端申请保证长时间连续上传不会中断。这个细节在实际项目中非常重要尤其是用户一次批量上传几十张图片的时候。2. 项目准备与核心配置2.1 存储桶与跨域配置的坑在动手写代码之前有两项配置必须在腾讯云控制台提前准备一个是创建存储桶另一个是配置CORS跨域规则。很多新手第一次做直传时会卡在报错上其实问题往往不在代码而是跨域规则没配好。创建存储桶时我建议把读写权限设置为“私有读写”。有的同学会图省事直接选“公有读私有写”这样文件可以通过固定链接被所有人访问但对于用户上传的头像、证件照这类数据来说并不合适。私有读写配合后端签名URL才能做到安全可控。CORS跨域规则是重中之重。浏览器端直传COS本质上就是浏览器向COS发起的AJAX请求必然受到同源策略限制。如果控制台里没有配置允许跨域的规则前端会直接报“CORS policy: No Access-Control-Allow-Origin header”这类错误。配置时需要注意几个点AllowedOrigin要写你实际部署的前端域名开发环境可能是localhost千万别漏了AllowedMethod至少要包含PUT、POST、GET、HEAD、DELETEAllowedHeader建议填*否则SDK上传时自定义的头部信息会被浏览器拦截ExposeHeader建议填ETag、x-cos-request-id等方便前端定位问题。2.2 临时密钥签名链路临时密钥的正确获取方式是前端直传方案的重点。腾讯云官方推荐的做法是前端调用自己的后端接口后端再用腾讯云的STS SDK去换取临时密钥。为什么要绕这一道因为长期密钥SecretId和SecretSecretKey是绝对不能暴露在前端代码里的一旦暴露任何人都可以拿着它操作你的整个COS账号轻则产生大量流量费用重则数据被删。而直接放在前端代码里的密钥等于把大门钥匙交给所有路过的人。后端签发的临时密钥包含四个核心字段credentials.tmpSecretId、credentials.tmpSecretKey、credentials.sessionToken和expiredTime。前三个字段会交给前端SDK初始化使用expiredTime是用来判断密钥是否需要刷新的。字段名在不同SDK版本里可能略有差异但整体结构一致。有的项目为了省事会让前端直接拼接COS API的签名算法自己用crypto-js计算签名。这个路子不是不行但计算签名要处理Host、Headers、URL参数等一系列细节一旦某个地方编码格式不对排查起来特别费劲。而且密钥还是得找个地方存。相比之下用官方SDK配合STS临时密钥既安全又省心是我实测下来最稳的方案。3. 核心代码实现与关键参数3.1 Upload组件侧的模板与状态管理Element-UI的Upload组件默认的上传方式是把自己的action指向一个后端接口靠组件内部封装的XHR去发请求。这种方式在走“后端中转”时确实简单但我们要改成前端直传COS就没有现成的后端接口可以指向了。好在Upload组件提供了http-request这个配置项可以让我们完全接管上传逻辑。我的模板结构大致是这样写的template div classupload-wrapper el-upload refuploadRef action# :show-file-listfalse :before-uploadbeforeUpload :http-requesthandleHttpRequest :on-successhandleSuccess :on-errorhandleError :on-progresshandleProgress :on-removehandleRemove :limit10 :on-exceedhandleExceed acceptimage/* multiple el-button typeprimary选择图片/el-button /el-upload div classfile-list div v-forfile in fileList :keyfile.uid classfile-item span{{ file.name }}/span el-progress :percentagefile.percent / /div /div /div /template有几个细节值得注意第一action属性传一个#占位因为http-request接管之后它会失效但如果不填组件内部校验会不通过。第二show-file-list我设置成了false因为默认的组件文件列表在直传场景下不好控制状态尤其牵扯到分片上传时组件内置的进度条和实际的分片进度很难对齐。所以我选择自己维护一个fileList数组完全掌控每张照片的状态。第三limit和on-exceed组合使用可以控制上传数量上限acceptimage/*用来限定文件类型但注意它只是弹窗筛选不是安全校验后端或COS侧最好再做一次校验。3.2 基于http-request接管上传流程http-request是Upload组件暴露给我们的一个“完全接管”的入口它接收一个配置对象包含file、onSuccess、onError、onProgress等信息。这个设计非常巧妙等于把组件的状态回调机制完整地交给我们自己控制。我的核心上传函数是这样组织的import COS from cos-js-sdk-v5; let cosInstance null; let taskMap new Map(); // 用于存储任务Id便于取消 // 向后端获取临时密钥 async function getCOSCredentials() { const response await axios.get(/api/cos/sts); const { tmpSecretId, tmpSecretKey, sessionToken, expiredTime } response.data; return { tmpSecretId, tmpSecretKey, sessionToken, expiredTime }; } // 初始化或复用COS实例 async function getCOSInstance() { if (cosInstance) return cosInstance; const credentials await getCOSCredentials(); if (!credentials.tmpSecretId || !credentials.tmpSecretKey || !credentials.sessionToken) { throw new Error(获取临时密钥失败); } cosInstance new COS({ getAuthorization: (options, callback) { // 每次请求前检查密钥是否临近过期如果过期则重新获取 const now Math.floor(Date.now() / 1000); if (credentials.expiredTime - now 60) { getCOSCredentials().then(newCredentials { Object.assign(credentials, newCredentials); callback({ TmpSecretId: credentials.tmpSecretId, TmpSecretKey: credentials.tmpSecretKey, SecurityToken: credentials.sessionToken, StartTime: now, ExpiredTime: credentials.expiredTime }); }).catch(error callback(error)); } else { callback({ TmpSecretId: credentials.tmpSecretId, TmpSecretKey: credentials.tmpSecretKey, SecurityToken: credentials.sessionToken, StartTime: now, ExpiredTime: credentials.expiredTime }); } } }); return cosInstance; }这里有个容易踩坑的地方getAuthorization不是只调用一次的。COS SDK在每次发请求前都会调它一次包括初始化、分片上传的每一个分片、完成合并请求等。如果每次都去请求后端拿新的密钥会产生大量不必要的请求。所以我做了一个简单的判断如果密钥剩余时间还超过60秒就直接复用缓存否则才重新获取。这个60秒的提前量是经验值给SDK留出网络波动和时钟偏差的空间。接下来是handleHttpRequest的实现。Upload组件传给它的参数中onProgress等回调是组件内置的但我们自己接管后必须手动调用它们才能让组件的状态机制继续工作。我的做法是让handleHttpRequest返回一个带abort()方法的对象这样组件在移除文件或取消上传时能主动中断我们正在进行的COS上传任务。async function handleHttpRequest({ file, onProgress, onSuccess, onError }) { const fileName file.name; const ext fileName.split(.).pop().toLowerCase(); const key uploads/${Date.now()}-${Math.floor(Math.random() * 10000)}.${ext}; const COS_OPTIONS { Bucket: your-bucket-name-1250000000, Region: ap-guangzhou, Key: key, Body: file, SliceSize: 1024 * 1024 * 5, // 大于5MB的文件自动分片 }; try { const instance await getCOSInstance(); const taskId instance.uploadFile({ ...COS_OPTIONS, onProgress: (data) { const percent Math.floor(data.percent * 100); onProgress({ percent }); }, onSuccess: (data) { const url https://your-bucket-name-1250000000.cos.ap-guangzhou.myqcloud.com/${key}; onSuccess({ url, key, data }); }, onError: (error) { onError(error); } }); taskMap.set(file.uid, taskId); return { abort() { instance.cancelTask(taskId); taskMap.delete(file.uid); } }; } catch (error) { onError(error); } }Key的设计需要多花点心思。我直接用uploads/前缀加时间戳和随机数拼接这样可以避免中文文件名在URL里出现编码问题也减少同名文件互相覆盖的风险。如果你有按用户ID分目录的需求也可以在Key里加上用户的标识比如uploads/user_12345/xxxxx.jpg这样管理起来更清晰。3.3 进度条、文件状态与取消机制自己接管上传之后进度条和文件状态必须同步维护。在我接手这个项目时发现一个经典问题Element-UI内置的el-upload文件列表有自己的status和percentage字段但直传COS时分片上传的进度是COS SDK回调的两者很容易对不上。这时候有两种选择一种是把show-file-list保持为true然后在onProgress回调里手动更新file.percentage字段另一种是像我的模板里那样完全隐藏内置列表自己渲染一个。我选择了后者原因有两个。第一内置列表的样式定制空间很小加上缩略图、重试按钮、取消按钮都要额外处理不如自己写灵活。第二直传场景下我们需要展示的进度粒度更细——单个文件切片数、整体上传进度、以及失败后的重试入口这些都是自定义列表更好做。我的fileList数据项设计为// fileList里的每一项 { uid: 唯一标识, name: example.jpg, status: uploading | success | error, percent: 0, url: , }onProgress回调更新percent和statusonSuccess更新url和statusonError只更新status。重试操作就是再次调用handleHttpRequest里那一整套逻辑。这里有个小技巧不要把COS的临时密钥和实例做成全局持久化的因为密钥会过期。我实际写代码时会在组件beforeDestroy钩子里调用instance.cancelAll()来清理未完成的任务防止页面销毁后COS的回调还在触发Vue组件更新导致控制台报错。3.4 后端STS接口的简单示例虽然这篇文章主要讲前端但后端的STS接口是整个链路能跑通的前提。我写了一个简化的Node.js示例核心原理是使用腾讯云STS SDK用自己服务端配置的永久密钥去换一个临时密钥。const STS require(qcloud-cos-sts); const config { SecretId: process.env.TENCENT_SECRET_ID, SecretKey: process.env.TENCENT_SECRET_KEY, DurationSeconds: 7200, Bucket: your-bucket-name-1250000000, Region: ap-guangzhou, }; router.get(/api/cos/sts, async (req, res) { // 这里一定要先校验用户登录态再执行以下逻辑 const shortBucketName config.Bucket.slice(0, config.Bucket.lastIndexOf(-)); const policy { version: 2.0, statement: [{ action: [ cos:PutObject, cos:PostObject, cos:UploadPart, cos:CompleteMultipartUpload, cos:AbortMultipartUpload, ], effect: allow, resource: [ qcs::cos:${config.Region}:uid/1250000000:${shortBucketName}-1250000000/uploads/*, ], condition: { ip_equal: { qcs:ip: req.ip }, }, }], }; const result await STS.getCredential({ secretId: config.SecretId, secretKey: config.SecretKey, policy, durationSeconds: config.DurationSeconds, }); res.json(result.credentials); });策略里的resource限制了临时密钥只能操作uploads/目录下的对象并且限定来源IP是当前请求的IP地址。这是安全上的一道双保险。限制目录的好处是即使临时密钥被截获攻击者也不能遍历或操作整个桶里的其他文件。我在线上的COS桶里除了uploads/还存了静态资源如果不加这条目录限制风险会大很多。4. 常见问题与排查技巧实录4.1 跨域报错怎么定位我见过最多的问题就是跨域报错。现象是控制台报Access to XMLHttpRequest at https://xxx.cos.ap-guangzhou.myqcloud.com/... from origin http://localhost:8080 has been blocked by CORS policy。很多朋友一看到这个就蒙了其实定位思路很清晰先确认COS桶的CORS配置里有没有包含你当前的前端域名再确认请求方法是不是都在AllowedMethod里最后确认AllowedHeader有没有设成*。有一个很容易忽略的坑CORS配置修改后浏览器和COS的边缘节点会有缓存。也就是说你在控制台改完规则立刻回前端刷新页面测试发现还是报同样的错这不一定是没改成功可能是缓存还没过期。建议等一两分钟再测或者用无痕窗口验证。我几次“改完无效”的假象最后都是缓存在作怪。4.2 上传成功但组件状态异常这个问题非常典型。表现是COS里文件已经传上去了但页面的文件状态一直停留在“上传中”或者进度条卡在99%不动。排查下来大部分原因是onProgress回调里percent字段的取法不对。COS SDK的onProgress回调返回的对象里percent是一个0到100的整数也可能带上小数而Element-UI的el-progress组件期望的是0到100的数字。有的版本里可能返回1.0这类浮点数有的返回0.123这种比例值如果你不统一单位就会出现“瞬间跳到100%后又回退”的情况。我习惯在回调里强制做一次Math.floor(data.percent)确保单位统一。另一个状态异常的来源是http-request没有正确返回abort方法。Element-UI的Upload组件在移除文件时会去调用fileList对应项的XHR对象的abort方法但自定义上传时我们并没有真正的XHR对象组件只能调用我们返回的对象上的abort。如果不返回这个方法移除文件时组件会报错或者干脆没反应。4.3 签名过期与并发问题签名过期是另一个高频坑。最典型的场景是用户打开上传页面超过半小时才开始选文件或者批量上传大文件时传了一半密钥过期了。前者可以通过在getAuthorization里检查过期时间解决后者则更麻烦因为密钥的刷新时机正好落在分片上传的中间——某个分片用旧密钥在传下一个分片已经开始请求新密钥了这种并发状态下偶尔会出现400或403异常。我的解决方案是给密钥刷新加一个互斥锁。用简单的Promise链让并发请求等待同一个刷新操作完成避免多个分片同时触发多次STS请求。具体实现可以是let credentialPromise null; function requestCredentials() { if (!credentialPromise) { credentialPromise getCOSCredentials() .then(data { credentialPromise null; return data; }) .catch(error { credentialPromise null; throw error; }); } return credentialPromise; }这样即使几十个分片同时需要新密钥也只有一个真正的STS请求在飞其余的全部复用同一个Promise的返回值。这个模式不只是COS上传可以用任何前端“一次性初始化”的异步资源比如SDK加载、token获取都适用。4.4 分片大小与并发参数的选择SliceSize参数决定了上传时是否启用分片以及分片的大小。我实测下来的经验是对于普通图片把SliceSize设为5MB即可对于几百MB的视频分片大小可以提高到10MB甚至20MB减少分片数量降低合并请求的压力。分片太小会导致发起大量HTTP请求性能反而下降太大则失去分片上传的断点续传优势。COS SDK内部对分片上传的并发数也有默认值通常不需要手动调。但如果你的用户普遍网络带宽很高可以适当调高并发数来加速上传如果网络质量不稳定反而应该降低并发数减少单个分片失败导致整个上传失败的概率。我一般是先按默认值跑然后在监控后台观察上传耗时和失败率再微调。5. 其他注意事项与补充5.1 完整的文件校验流程直传模式下前端的文件校验不能只靠accept属性。我在beforeUpload里会做以下检查文件大小是否超过限制、文件类型是否符合白名单、文件名后缀是否在允许列表中。COS SDK虽然会做服务端的校验但如果前端能把明显不合法的请求拦截下来既减少无效上传也避免用户被莫名其妙的错误提示困扰。function beforeUpload(file) { const MAX_SIZE 20 * 1024 * 1024; // 20MB const WHITE_LIST [image/jpeg, image/png, image/gif, image/webp]; if (file.size MAX_SIZE) { this.$message.error(文件大小不能超过20MB); return false; } if (WHITE_LIST.indexOf(file.type) -1) { this.$message.error(仅支持jpg、png、gif、webp格式); return false; } return true; }注意file.type在部分浏览器里可能为空字符串尤其是某些压缩包或者特殊格式图片。所以不能完全依赖MIME类型要同时保留后缀名的判断逻辑两种校验双保险。5.2 隐私与安全的几个小建议前端直传COS虽然把存储压力转移到了云端但安全问题不能忽视。除了前面提到的STS临时密钥、目录权限限定之外我还建议在COS控制台开启防盗链限制Referer来源域名防止他人盗用图片链接。另外私有读写的桶要配合生成临时URL供前端显示缩略图这时候可以用COS SDK的getObjectUrl方法生成带签名、带有效期的访问地址。还有一个经常被忽略的点上传完成后业务后端最好通过COS的事件通知或回调接口做二次确认。也就是说前端告诉后端“我传成功了”后端可以再调COS API验证这个文件确实存在并且校验它的大小、类型是否和预期一致。这样能防止前端伪造上传成功的信息在安全级别要求高的业务里很有必要。5.3 后续扩展方向这个方案跑通之后可以扩展的点其实很多。比如结合COS的图片处理API在上传完成后生成不同尺寸的缩略图或者把上传记录写入数据库做成一个完整的“附件中心”再或者加上相似度检查、图片审核功能。对我自己来说最实用的是把上传回调里生成的URL直接回填到表单数据里整个流程就顺畅闭环了。最后再分享一个我调试时觉得特别好用的技巧在开发环境下可以用Vue的mixin全局注入一个调试开关当?debugcos出现在URL里时把COS SDK每次请求的requestId、statusCode、taskId都打印到控制台。这样在线上定位问题的时候只要让用户带上这个参数访问就能拿到完整的上传链路日志比自己猜要高效得多。这个习惯帮我省了无数次远程排查的时间也算是一个值得留存的小工具。
