1. 方案選型與整體思路拆解1.1 為什么最終選了前端直傳先聊一個(gè)很多朋友都會(huì)糾結(jié)的問(wèn)題文件上傳到底該走“后端中轉(zhuǎn)”還是“前端直傳”我最早做這個(gè)項(xiàng)目時(shí)第一版用的是后端中轉(zhuǎn)——前端把文件POST給后端接口后端再轉(zhuǎn)存到對(duì)象存儲(chǔ)。這樣做的優(yōu)點(diǎn)是對(duì)前端友好代碼寫(xiě)起來(lái)簡(jiǎn)單甚至后端框架自帶的上傳邏輯改改就能用。但項(xiàng)目一上線問(wèn)題就來(lái)了大文件上傳時(shí)服務(wù)器帶寬成了瓶頸上傳一個(gè)幾十MB的視頻后端服務(wù)器的CPU和內(nèi)存波動(dòng)非常明顯好幾個(gè)并發(fā)上來(lái)之后接口響應(yīng)都開(kāi)始變慢嚴(yán)重的時(shí)候把正常業(yè)務(wù)請(qǐng)求也拖垮了。后來(lái)我換成了“前端直傳騰訊云COS”的方案瀏覽器端拿到臨時(shí)密鑰后把文件直接傳往騰訊云的對(duì)象存儲(chǔ)桶整個(gè)過(guò)程不經(jīng)過(guò)自己的業(yè)務(wù)服務(wù)器。好處是顯而易見(jiàn)的帶寬消耗被分?jǐn)偟皆茝S商的CDN和存儲(chǔ)節(jié)點(diǎn)上自己的服務(wù)器只管簽發(fā)一次臨時(shí)密鑰實(shí)際傳輸壓力幾乎為零。而且騰訊云COS在中國(guó)大陸區(qū)域的傳輸速度本身就有保障大文件上傳體驗(yàn)比走業(yè)務(wù)服務(wù)器中轉(zhuǎn)好很多。這個(gè)方案非常適合有較多圖片、視頻、附件上傳需求的Web應(yīng)用尤其是后臺(tái)管理系統(tǒng)這類常見(jiàn)場(chǎng)景。我調(diào)研過(guò)市面上幾種方案一是純后端上傳適合文件類型單一、并發(fā)量低、業(yè)務(wù)對(duì)文件安全性要求極高的場(chǎng)景二是前端直傳加上服務(wù)端簽名適合大部分中大型業(yè)務(wù)既不需要暴露長(zhǎng)期密鑰又不會(huì)給服務(wù)器帶來(lái)太大壓力三是前端直傳、后端回調(diào)校驗(yàn)適合需要強(qiáng)一致性的場(chǎng)景?？紤]到項(xiàng)目使用的是VueElement-UI技術(shù)棧我最終采用了第二種也就是基于Element-UI Upload組件的自定義上傳能力配合axios簽發(fā)臨時(shí)密鑰再用騰訊云官方SDK完成文件上傳。1.2 整體鏈路是怎么設(shè)計(jì)的整個(gè)上傳鏈路由三個(gè)角色構(gòu)成瀏覽器端、業(yè)務(wù)后端、騰訊云COS。業(yè)務(wù)后端負(fù)責(zé)提供臨時(shí)密鑰和必要的簽名信息騰訊云COS負(fù)責(zé)實(shí)際存儲(chǔ)瀏覽器端則是整個(gè)流程的組織者。具體的執(zhí)行順序是這樣的前端用戶選擇文件后先向自己的業(yè)務(wù)后端請(qǐng)求STS臨時(shí)密鑰Security Token Service后端校驗(yàn)用戶登錄態(tài)和上傳權(quán)限后調(diào)用騰訊云的STS接口簽發(fā)臨時(shí)憑證返回給前端。前端拿到AccessKeyId、SecretAccessKey、SessionToken和過(guò)期時(shí)間后初始化騰訊云COS SDK再把文件切片并逐個(gè)上傳到目標(biāo)存儲(chǔ)桶。整個(gè)過(guò)程用戶感知不到中間步驟體驗(yàn)和一個(gè)普通的上傳表單完全一致但底層的數(shù)據(jù)流已經(jīng)不經(jīng)過(guò)自己的服務(wù)器了。這里有一個(gè)關(guān)鍵點(diǎn)臨時(shí)密鑰是有時(shí)效性的默認(rèn)情況下可能只有幾十分鐘到幾小時(shí)。如果用戶上傳的文件非常多、耗時(shí)很長(zhǎng)密鑰過(guò)期后上傳就會(huì)失敗。所以我在設(shè)計(jì)時(shí)加了一個(gè)密鑰緩存和刷新機(jī)制第一次請(qǐng)求后把臨時(shí)密鑰存在前端快要過(guò)期前自動(dòng)重新向后端申請(qǐng)保證長(zhǎng)時(shí)間連續(xù)上傳不會(huì)中斷。這個(gè)細(xì)節(jié)在實(shí)際項(xiàng)目中非常重要尤其是用戶一次批量上傳幾十張圖片的時(shí)候。2. 項(xiàng)目準(zhǔn)備與核心配置2.1 存儲(chǔ)桶與跨域配置的坑在動(dòng)手寫(xiě)代碼之前有兩項(xiàng)配置必須在騰訊云控制臺(tái)提前準(zhǔn)備一個(gè)是創(chuàng)建存儲(chǔ)桶另一個(gè)是配置CORS跨域規(guī)則。很多新手第一次做直傳時(shí)會(huì)卡在報(bào)錯(cuò)上其實(shí)問(wèn)題往往不在代碼而是跨域規(guī)則沒(méi)配好。創(chuàng)建存儲(chǔ)桶時(shí)我建議把讀寫(xiě)權(quán)限設(shè)置為“私有讀寫(xiě)”。有的同學(xué)會(huì)圖省事直接選“公有讀私有寫(xiě)”這樣文件可以通過(guò)固定鏈接被所有人訪問(wèn)但對(duì)于用戶上傳的頭像、證件照這類數(shù)據(jù)來(lái)說(shuō)并不合適。私有讀寫(xiě)配合后端簽名URL才能做到安全可控。CORS跨域規(guī)則是重中之重。瀏覽器端直傳COS本質(zhì)上就是瀏覽器向COS發(fā)起的AJAX請(qǐng)求必然受到同源策略限制。如果控制臺(tái)里沒(méi)有配置允許跨域的規(guī)則前端會(huì)直接報(bào)“CORS policy: No Access-Control-Allow-Origin header”這類錯(cuò)誤。配置時(shí)需要注意幾個(gè)點(diǎn)AllowedOrigin要寫(xiě)你實(shí)際部署的前端域名開(kāi)發(fā)環(huán)境可能是localhost千萬(wàn)別漏了AllowedMethod至少要包含PUT、POST、GET、HEAD、DELETEAllowedHeader建議填*否則SDK上傳時(shí)自定義的頭部信息會(huì)被瀏覽器攔截ExposeHeader建議填ETag、x-cos-request-id等方便前端定位問(wèn)題。2.2 臨時(shí)密鑰簽名鏈路臨時(shí)密鑰的正確獲取方式是前端直傳方案的重點(diǎn)。騰訊云官方推薦的做法是前端調(diào)用自己的后端接口后端再用騰訊云的STS SDK去換取臨時(shí)密鑰。為什么要繞這一道因?yàn)殚L(zhǎng)期密鑰SecretId和SecretSecretKey是絕對(duì)不能暴露在前端代碼里的一旦暴露任何人都可以拿著它操作你的整個(gè)COS賬號(hào)輕則產(chǎn)生大量流量費(fèi)用重則數(shù)據(jù)被刪。而直接放在前端代碼里的密鑰等于把大門鑰匙交給所有路過(guò)的人。后端簽發(fā)的臨時(shí)密鑰包含四個(gè)核心字段credentials.tmpSecretId、credentials.tmpSecretKey、credentials.sessionToken和expiredTime。前三個(gè)字段會(huì)交給前端SDK初始化使用expiredTime是用來(lái)判斷密鑰是否需要刷新的。字段名在不同SDK版本里可能略有差異但整體結(jié)構(gòu)一致。有的項(xiàng)目為了省事會(huì)讓前端直接拼接COS API的簽名算法自己用crypto-js計(jì)算簽名。這個(gè)路子不是不行但計(jì)算簽名要處理Host、Headers、URL參數(shù)等一系列細(xì)節(jié)一旦某個(gè)地方編碼格式不對(duì)排查起來(lái)特別費(fèi)勁。而且密鑰還是得找個(gè)地方存。相比之下用官方SDK配合STS臨時(shí)密鑰既安全又省心是我實(shí)測(cè)下來(lái)最穩(wěn)的方案。3. 核心代碼實(shí)現(xiàn)與關(guān)鍵參數(shù)3.1 Upload組件側(cè)的模板與狀態(tài)管理Element-UI的Upload組件默認(rèn)的上傳方式是把自己的action指向一個(gè)后端接口靠組件內(nèi)部封裝的XHR去發(fā)請(qǐng)求。這種方式在走“后端中轉(zhuǎn)”時(shí)確實(shí)簡(jiǎn)單但我們要改成前端直傳COS就沒(méi)有現(xiàn)成的后端接口可以指向了。好在Upload組件提供了http-request這個(gè)配置項(xiàng)可以讓我們完全接管上傳邏輯。我的模板結(jié)構(gòu)大致是這樣寫(xiě)的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有幾個(gè)細(xì)節(jié)值得注意第一action屬性傳一個(gè)#占位因?yàn)閔ttp-request接管之后它會(huì)失效但如果不填組件內(nèi)部校驗(yàn)會(huì)不通過(guò)。第二show-file-list我設(shè)置成了false因?yàn)槟J(rèn)的組件文件列表在直傳場(chǎng)景下不好控制狀態(tài)尤其牽扯到分片上傳時(shí)組件內(nèi)置的進(jìn)度條和實(shí)際的分片進(jìn)度很難對(duì)齊。所以我選擇自己維護(hù)一個(gè)fileList數(shù)組完全掌控每張照片的狀態(tài)。第三limit和on-exceed組合使用可以控制上傳數(shù)量上限acceptimage/*用來(lái)限定文件類型但注意它只是彈窗篩選不是安全校驗(yàn)后端或COS側(cè)最好再做一次校驗(yàn)。3.2 基于http-request接管上傳流程http-request是Upload組件暴露給我們的一個(gè)“完全接管”的入口它接收一個(gè)配置對(duì)象包含file、onSuccess、onError、onProgress等信息。這個(gè)設(shè)計(jì)非常巧妙等于把組件的狀態(tài)回調(diào)機(jī)制完整地交給我們自己控制。我的核心上傳函數(shù)是這樣組織的import COS from cos-js-sdk-v5; let cosInstance null; let taskMap new Map(); // 用于存儲(chǔ)任務(wù)Id便于取消 // 向后端獲取臨時(shí)密鑰 async function getCOSCredentials() { const response await axios.get(/api/cos/sts); const { tmpSecretId, tmpSecretKey, sessionToken, expiredTime } response.data; return { tmpSecretId, tmpSecretKey, sessionToken, expiredTime }; } // 初始化或復(fù)用COS實(shí)例 async function getCOSInstance() { if (cosInstance) return cosInstance; const credentials await getCOSCredentials(); if (!credentials.tmpSecretId || !credentials.tmpSecretKey || !credentials.sessionToken) { throw new Error(獲取臨時(shí)密鑰失敗); } cosInstance new COS({ getAuthorization: (options, callback) { // 每次請(qǐng)求前檢查密鑰是否臨近過(guò)期如果過(guò)期則重新獲取 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; }這里有個(gè)容易踩坑的地方getAuthorization不是只調(diào)用一次的。COS SDK在每次發(fā)請(qǐng)求前都會(huì)調(diào)它一次包括初始化、分片上傳的每一個(gè)分片、完成合并請(qǐng)求等。如果每次都去請(qǐng)求后端拿新的密鑰會(huì)產(chǎn)生大量不必要的請(qǐng)求。所以我做了一個(gè)簡(jiǎn)單的判斷如果密鑰剩余時(shí)間還超過(guò)60秒就直接復(fù)用緩存否則才重新獲取。這個(gè)60秒的提前量是經(jīng)驗(yàn)值給SDK留出網(wǎng)絡(luò)波動(dòng)和時(shí)鐘偏差的空間。接下來(lái)是handleHttpRequest的實(shí)現(xiàn)。Upload組件傳給它的參數(shù)中onProgress等回調(diào)是組件內(nèi)置的但我們自己接管后必須手動(dòng)調(diào)用它們才能讓組件的狀態(tài)機(jī)制繼續(xù)工作。我的做法是讓handleHttpRequest返回一個(gè)帶abort()方法的對(duì)象這樣組件在移除文件或取消上傳時(shí)能主動(dòng)中斷我們正在進(jìn)行的COS上傳任務(wù)。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的文件自動(dòng)分片 }; 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的設(shè)計(jì)需要多花點(diǎn)心思。我直接用uploads/前綴加時(shí)間戳和隨機(jī)數(shù)拼接這樣可以避免中文文件名在URL里出現(xiàn)編碼問(wèn)題也減少同名文件互相覆蓋的風(fēng)險(xiǎn)。如果你有按用戶ID分目錄的需求也可以在Key里加上用戶的標(biāo)識(shí)比如uploads/user_12345/xxxxx.jpg這樣管理起來(lái)更清晰。3.3 進(jìn)度條、文件狀態(tài)與取消機(jī)制自己接管上傳之后進(jìn)度條和文件狀態(tài)必須同步維護(hù)。在我接手這個(gè)項(xiàng)目時(shí)發(fā)現(xiàn)一個(gè)經(jīng)典問(wèn)題Element-UI內(nèi)置的el-upload文件列表有自己的status和percentage字段但直傳COS時(shí)分片上傳的進(jìn)度是COS SDK回調(diào)的兩者很容易對(duì)不上。這時(shí)候有兩種選擇一種是把show-file-list保持為true然后在onProgress回調(diào)里手動(dòng)更新file.percentage字段另一種是像我的模板里那樣完全隱藏內(nèi)置列表自己渲染一個(gè)。我選擇了后者原因有兩個(gè)。第一內(nèi)置列表的樣式定制空間很小加上縮略圖、重試按鈕、取消按鈕都要額外處理不如自己寫(xiě)靈活。第二直傳場(chǎng)景下我們需要展示的進(jìn)度粒度更細(xì)——單個(gè)文件切片數(shù)、整體上傳進(jìn)度、以及失敗后的重試入口這些都是自定義列表更好做。我的fileList數(shù)據(jù)項(xiàng)設(shè)計(jì)為// fileList里的每一項(xiàng) { uid: 唯一標(biāo)識(shí), name: example.jpg, status: uploading | success | error, percent: 0, url: , }onProgress回調(diào)更新percent和statusonSuccess更新url和statusonError只更新status。重試操作就是再次調(diào)用handleHttpRequest里那一整套邏輯。這里有個(gè)小技巧不要把COS的臨時(shí)密鑰和實(shí)例做成全局持久化的因?yàn)槊荑€會(huì)過(guò)期。我實(shí)際寫(xiě)代碼時(shí)會(huì)在組件beforeDestroy鉤子里調(diào)用instance.cancelAll()來(lái)清理未完成的任務(wù)防止頁(yè)面銷毀后COS的回調(diào)還在觸發(fā)Vue組件更新導(dǎo)致控制臺(tái)報(bào)錯(cuò)。3.4 后端STS接口的簡(jiǎn)單示例雖然這篇文章主要講前端但后端的STS接口是整個(gè)鏈路能跑通的前提。我寫(xiě)了一個(gè)簡(jiǎn)化的Node.js示例核心原理是使用騰訊云STS SDK用自己服務(wù)端配置的永久密鑰去換一個(gè)臨時(shí)密鑰。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) { // 這里一定要先校驗(yàn)用戶登錄態(tài)再執(zhí)行以下邏輯 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限制了臨時(shí)密鑰只能操作uploads/目錄下的對(duì)象并且限定來(lái)源IP是當(dāng)前請(qǐng)求的IP地址。這是安全上的一道雙保險(xiǎn)。限制目錄的好處是即使臨時(shí)密鑰被截獲攻擊者也不能遍歷或操作整個(gè)桶里的其他文件。我在線上的COS桶里除了uploads/還存了靜態(tài)資源如果不加這條目錄限制風(fēng)險(xiǎn)會(huì)大很多。4. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄4.1 跨域報(bào)錯(cuò)怎么定位我見(jiàn)過(guò)最多的問(wèn)題就是跨域報(bào)錯(cuò)?，F(xiàn)象是控制臺(tái)報(bào)Access to XMLHttpRequest at https://xxx.cos.ap-guangzhou.myqcloud.com/... from origin http://localhost:8080 has been blocked by CORS policy。很多朋友一看到這個(gè)就蒙了其實(shí)定位思路很清晰先確認(rèn)COS桶的CORS配置里有沒(méi)有包含你當(dāng)前的前端域名再確認(rèn)請(qǐng)求方法是不是都在AllowedMethod里最后確認(rèn)AllowedHeader有沒(méi)有設(shè)成*。有一個(gè)很容易忽略的坑CORS配置修改后瀏覽器和COS的邊緣節(jié)點(diǎn)會(huì)有緩存。也就是說(shuō)你在控制臺(tái)改完規(guī)則立刻回前端刷新頁(yè)面測(cè)試發(fā)現(xiàn)還是報(bào)同樣的錯(cuò)這不一定是沒(méi)改成功可能是緩存還沒(méi)過(guò)期。建議等一兩分鐘再測(cè)或者用無(wú)痕窗口驗(yàn)證。我?guī)状巍案耐隉o(wú)效”的假象最后都是緩存在作怪。4.2 上傳成功但組件狀態(tài)異常這個(gè)問(wèn)題非常典型。表現(xiàn)是COS里文件已經(jīng)傳上去了但頁(yè)面的文件狀態(tài)一直停留在“上傳中”或者進(jìn)度條卡在99%不動(dòng)。排查下來(lái)大部分原因是onProgress回調(diào)里percent字段的取法不對(duì)。COS SDK的onProgress回調(diào)返回的對(duì)象里percent是一個(gè)0到100的整數(shù)也可能帶上小數(shù)而Element-UI的el-progress組件期望的是0到100的數(shù)字。有的版本里可能返回1.0這類浮點(diǎn)數(shù)有的返回0.123這種比例值如果你不統(tǒng)一單位就會(huì)出現(xiàn)“瞬間跳到100%后又回退”的情況。我習(xí)慣在回調(diào)里強(qiáng)制做一次Math.floor(data.percent)確保單位統(tǒng)一。另一個(gè)狀態(tài)異常的來(lái)源是http-request沒(méi)有正確返回abort方法。Element-UI的Upload組件在移除文件時(shí)會(huì)去調(diào)用fileList對(duì)應(yīng)項(xiàng)的XHR對(duì)象的abort方法但自定義上傳時(shí)我們并沒(méi)有真正的XHR對(duì)象組件只能調(diào)用我們返回的對(duì)象上的abort。如果不返回這個(gè)方法移除文件時(shí)組件會(huì)報(bào)錯(cuò)或者干脆沒(méi)反應(yīng)。4.3 簽名過(guò)期與并發(fā)問(wèn)題簽名過(guò)期是另一個(gè)高頻坑。最典型的場(chǎng)景是用戶打開(kāi)上傳頁(yè)面超過(guò)半小時(shí)才開(kāi)始選文件或者批量上傳大文件時(shí)傳了一半密鑰過(guò)期了。前者可以通過(guò)在getAuthorization里檢查過(guò)期時(shí)間解決后者則更麻煩因?yàn)槊荑€的刷新時(shí)機(jī)正好落在分片上傳的中間——某個(gè)分片用舊密鑰在傳下一個(gè)分片已經(jīng)開(kāi)始請(qǐng)求新密鑰了這種并發(fā)狀態(tài)下偶爾會(huì)出現(xiàn)400或403異常。我的解決方案是給密鑰刷新加一個(gè)互斥鎖。用簡(jiǎn)單的Promise鏈讓并發(fā)請(qǐng)求等待同一個(gè)刷新操作完成避免多個(gè)分片同時(shí)觸發(fā)多次STS請(qǐng)求。具體實(shí)現(xiàn)可以是let credentialPromise null; function requestCredentials() { if (!credentialPromise) { credentialPromise getCOSCredentials() .then(data { credentialPromise null; return data; }) .catch(error { credentialPromise null; throw error; }); } return credentialPromise; }這樣即使幾十個(gè)分片同時(shí)需要新密鑰也只有一個(gè)真正的STS請(qǐng)求在飛其余的全部復(fù)用同一個(gè)Promise的返回值。這個(gè)模式不只是COS上傳可以用任何前端“一次性初始化”的異步資源比如SDK加載、token獲取都適用。4.4 分片大小與并發(fā)參數(shù)的選擇SliceSize參數(shù)決定了上傳時(shí)是否啟用分片以及分片的大小。我實(shí)測(cè)下來(lái)的經(jīng)驗(yàn)是對(duì)于普通圖片把SliceSize設(shè)為5MB即可對(duì)于幾百M(fèi)B的視頻分片大小可以提高到10MB甚至20MB減少分片數(shù)量降低合并請(qǐng)求的壓力。分片太小會(huì)導(dǎo)致發(fā)起大量HTTP請(qǐng)求性能反而下降太大則失去分片上傳的斷點(diǎn)續(xù)傳優(yōu)勢(shì)。COS SDK內(nèi)部對(duì)分片上傳的并發(fā)數(shù)也有默認(rèn)值通常不需要手動(dòng)調(diào)。但如果你的用戶普遍網(wǎng)絡(luò)帶寬很高可以適當(dāng)調(diào)高并發(fā)數(shù)來(lái)加速上傳如果網(wǎng)絡(luò)質(zhì)量不穩(wěn)定反而應(yīng)該降低并發(fā)數(shù)減少單個(gè)分片失敗導(dǎo)致整個(gè)上傳失敗的概率。我一般是先按默認(rèn)值跑然后在監(jiān)控后臺(tái)觀察上傳耗時(shí)和失敗率再微調(diào)。5. 其他注意事項(xiàng)與補(bǔ)充5.1 完整的文件校驗(yàn)流程直傳模式下前端的文件校驗(yàn)不能只靠accept屬性。我在beforeUpload里會(huì)做以下檢查文件大小是否超過(guò)限制、文件類型是否符合白名單、文件名后綴是否在允許列表中。COS SDK雖然會(huì)做服務(wù)端的校驗(yàn)但如果前端能把明顯不合法的請(qǐng)求攔截下來(lái)既減少無(wú)效上傳也避免用戶被莫名其妙的錯(cuò)誤提示困擾。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(文件大小不能超過(guò)20MB); return false; } if (WHITE_LIST.indexOf(file.type) -1) { this.$message.error(僅支持jpg、png、gif、webp格式); return false; } return true; }注意file.type在部分瀏覽器里可能為空字符串尤其是某些壓縮包或者特殊格式圖片。所以不能完全依賴MIME類型要同時(shí)保留后綴名的判斷邏輯兩種校驗(yàn)雙保險(xiǎn)。5.2 隱私與安全的幾個(gè)小建議前端直傳COS雖然把存儲(chǔ)壓力轉(zhuǎn)移到了云端但安全問(wèn)題不能忽視。除了前面提到的STS臨時(shí)密鑰、目錄權(quán)限限定之外我還建議在COS控制臺(tái)開(kāi)啟防盜鏈限制Referer來(lái)源域名防止他人盜用圖片鏈接。另外私有讀寫(xiě)的桶要配合生成臨時(shí)URL供前端顯示縮略圖這時(shí)候可以用COS SDK的getObjectUrl方法生成帶簽名、帶有效期的訪問(wèn)地址。還有一個(gè)經(jīng)常被忽略的點(diǎn)上傳完成后業(yè)務(wù)后端最好通過(guò)COS的事件通知或回調(diào)接口做二次確認(rèn)。也就是說(shuō)前端告訴后端“我傳成功了”后端可以再調(diào)COS API驗(yàn)證這個(gè)文件確實(shí)存在并且校驗(yàn)它的大小、類型是否和預(yù)期一致。這樣能防止前端偽造上傳成功的信息在安全級(jí)別要求高的業(yè)務(wù)里很有必要。5.3 后續(xù)擴(kuò)展方向這個(gè)方案跑通之后可以擴(kuò)展的點(diǎn)其實(shí)很多。比如結(jié)合COS的圖片處理API在上傳完成后生成不同尺寸的縮略圖或者把上傳記錄寫(xiě)入數(shù)據(jù)庫(kù)做成一個(gè)完整的“附件中心”再或者加上相似度檢查、圖片審核功能。對(duì)我自己來(lái)說(shuō)最實(shí)用的是把上傳回調(diào)里生成的URL直接回填到表單數(shù)據(jù)里整個(gè)流程就順暢閉環(huán)了。最后再分享一個(gè)我調(diào)試時(shí)覺(jué)得特別好用的技巧在開(kāi)發(fā)環(huán)境下可以用Vue的mixin全局注入一個(gè)調(diào)試開(kāi)關(guān)當(dāng)?debugcos出現(xiàn)在URL里時(shí)把COS SDK每次請(qǐng)求的requestId、statusCode、taskId都打印到控制臺(tái)。這樣在線上定位問(wèn)題的時(shí)候只要讓用戶帶上這個(gè)參數(shù)訪問(wèn)就能拿到完整的上傳鏈路日志比自己猜要高效得多。這個(gè)習(xí)慣幫我省了無(wú)數(shù)次遠(yuǎn)程排查的時(shí)間也算是一個(gè)值得留存的小工具。 Vue+Element-UI前端直傳騰訊云COS文件上傳方案詳解
1. 方案選型與整體思路拆解1.1 為什么最終選了前端直傳先聊一個(gè)很多朋友都會(huì)糾結(jié)的問(wèn)題文件上傳到底該走“后端中轉(zhuǎn)”還是“前端直傳”我最早做這個(gè)項(xiàng)目時(shí)第一版用的是后端中轉(zhuǎn)——前端把文件POST給后端接口后端再轉(zhuǎn)存到對(duì)象存儲(chǔ)。這樣做的優(yōu)點(diǎn)是對(duì)前端友好代碼寫(xiě)起來(lái)簡(jiǎn)單甚至后端框架自帶的上傳邏輯改改就能用。但項(xiàng)目一上線問(wèn)題就來(lái)了大文件上傳時(shí)服務(wù)器帶寬成了瓶頸上傳一個(gè)幾十MB的視頻后端服務(wù)器的CPU和內(nèi)存波動(dòng)非常明顯好幾個(gè)并發(fā)上來(lái)之后接口響應(yīng)都開(kāi)始變慢嚴(yán)重的時(shí)候把正常業(yè)務(wù)請(qǐng)求也拖垮了。后來(lái)我換成了“前端直傳騰訊云COS”的方案瀏覽器端拿到臨時(shí)密鑰后把文件直接傳往騰訊云的對(duì)象存儲(chǔ)桶整個(gè)過(guò)程不經(jīng)過(guò)自己的業(yè)務(wù)服務(wù)器。好處是顯而易見(jiàn)的帶寬消耗被分?jǐn)偟皆茝S商的CDN和存儲(chǔ)節(jié)點(diǎn)上自己的服務(wù)器只管簽發(fā)一次臨時(shí)密鑰實(shí)際傳輸壓力幾乎為零。而且騰訊云COS在中國(guó)大陸區(qū)域的傳輸速度本身就有保障大文件上傳體驗(yàn)比走業(yè)務(wù)服務(wù)器中轉(zhuǎn)好很多。這個(gè)方案非常適合有較多圖片、視頻、附件上傳需求的Web應(yīng)用尤其是后臺(tái)管理系統(tǒng)這類常見(jiàn)場(chǎng)景。我調(diào)研過(guò)市面上幾種方案一是純后端上傳適合文件類型單一、并發(fā)量低、業(yè)務(wù)對(duì)文件安全性要求極高的場(chǎng)景二是前端直傳加上服務(wù)端簽名適合大部分中大型業(yè)務(wù)既不需要暴露長(zhǎng)期密鑰又不會(huì)給服務(wù)器帶來(lái)太大壓力三是前端直傳、后端回調(diào)校驗(yàn)適合需要強(qiáng)一致性的場(chǎng)景?？紤]到項(xiàng)目使用的是VueElement-UI技術(shù)棧我最終采用了第二種也就是基于Element-UI Upload組件的自定義上傳能力配合axios簽發(fā)臨時(shí)密鑰再用騰訊云官方SDK完成文件上傳。1.2 整體鏈路是怎么設(shè)計(jì)的整個(gè)上傳鏈路由三個(gè)角色構(gòu)成瀏覽器端、業(yè)務(wù)后端、騰訊云COS。業(yè)務(wù)后端負(fù)責(zé)提供臨時(shí)密鑰和必要的簽名信息騰訊云COS負(fù)責(zé)實(shí)際存儲(chǔ)瀏覽器端則是整個(gè)流程的組織者。具體的執(zhí)行順序是這樣的前端用戶選擇文件后先向自己的業(yè)務(wù)后端請(qǐng)求STS臨時(shí)密鑰Security Token Service后端校驗(yàn)用戶登錄態(tài)和上傳權(quán)限后調(diào)用騰訊云的STS接口簽發(fā)臨時(shí)憑證返回給前端。前端拿到AccessKeyId、SecretAccessKey、SessionToken和過(guò)期時(shí)間后初始化騰訊云COS SDK再把文件切片并逐個(gè)上傳到目標(biāo)存儲(chǔ)桶。整個(gè)過(guò)程用戶感知不到中間步驟體驗(yàn)和一個(gè)普通的上傳表單完全一致但底層的數(shù)據(jù)流已經(jīng)不經(jīng)過(guò)自己的服務(wù)器了。這里有一個(gè)關(guān)鍵點(diǎn)臨時(shí)密鑰是有時(shí)效性的默認(rèn)情況下可能只有幾十分鐘到幾小時(shí)。如果用戶上傳的文件非常多、耗時(shí)很長(zhǎng)密鑰過(guò)期后上傳就會(huì)失敗。所以我在設(shè)計(jì)時(shí)加了一個(gè)密鑰緩存和刷新機(jī)制第一次請(qǐng)求后把臨時(shí)密鑰存在前端快要過(guò)期前自動(dòng)重新向后端申請(qǐng)保證長(zhǎng)時(shí)間連續(xù)上傳不會(huì)中斷。這個(gè)細(xì)節(jié)在實(shí)際項(xiàng)目中非常重要尤其是用戶一次批量上傳幾十張圖片的時(shí)候。2. 項(xiàng)目準(zhǔn)備與核心配置2.1 存儲(chǔ)桶與跨域配置的坑在動(dòng)手寫(xiě)代碼之前有兩項(xiàng)配置必須在騰訊云控制臺(tái)提前準(zhǔn)備一個(gè)是創(chuàng)建存儲(chǔ)桶另一個(gè)是配置CORS跨域規(guī)則。很多新手第一次做直傳時(shí)會(huì)卡在報(bào)錯(cuò)上其實(shí)問(wèn)題往往不在代碼而是跨域規(guī)則沒(méi)配好。創(chuàng)建存儲(chǔ)桶時(shí)我建議把讀寫(xiě)權(quán)限設(shè)置為“私有讀寫(xiě)”。有的同學(xué)會(huì)圖省事直接選“公有讀私有寫(xiě)”這樣文件可以通過(guò)固定鏈接被所有人訪問(wèn)但對(duì)于用戶上傳的頭像、證件照這類數(shù)據(jù)來(lái)說(shuō)并不合適。私有讀寫(xiě)配合后端簽名URL才能做到安全可控。CORS跨域規(guī)則是重中之重。瀏覽器端直傳COS本質(zhì)上就是瀏覽器向COS發(fā)起的AJAX請(qǐng)求必然受到同源策略限制。如果控制臺(tái)里沒(méi)有配置允許跨域的規(guī)則前端會(huì)直接報(bào)“CORS policy: No Access-Control-Allow-Origin header”這類錯(cuò)誤。配置時(shí)需要注意幾個(gè)點(diǎn)AllowedOrigin要寫(xiě)你實(shí)際部署的前端域名開(kāi)發(fā)環(huán)境可能是localhost千萬(wàn)別漏了AllowedMethod至少要包含PUT、POST、GET、HEAD、DELETEAllowedHeader建議填*否則SDK上傳時(shí)自定義的頭部信息會(huì)被瀏覽器攔截ExposeHeader建議填ETag、x-cos-request-id等方便前端定位問(wèn)題。2.2 臨時(shí)密鑰簽名鏈路臨時(shí)密鑰的正確獲取方式是前端直傳方案的重點(diǎn)。騰訊云官方推薦的做法是前端調(diào)用自己的后端接口后端再用騰訊云的STS SDK去換取臨時(shí)密鑰。為什么要繞這一道因?yàn)殚L(zhǎng)期密鑰SecretId和SecretSecretKey是絕對(duì)不能暴露在前端代碼里的一旦暴露任何人都可以拿著它操作你的整個(gè)COS賬號(hào)輕則產(chǎn)生大量流量費(fèi)用重則數(shù)據(jù)被刪。而直接放在前端代碼里的密鑰等于把大門鑰匙交給所有路過(guò)的人。后端簽發(fā)的臨時(shí)密鑰包含四個(gè)核心字段credentials.tmpSecretId、credentials.tmpSecretKey、credentials.sessionToken和expiredTime。前三個(gè)字段會(huì)交給前端SDK初始化使用expiredTime是用來(lái)判斷密鑰是否需要刷新的。字段名在不同SDK版本里可能略有差異但整體結(jié)構(gòu)一致。有的項(xiàng)目為了省事會(huì)讓前端直接拼接COS API的簽名算法自己用crypto-js計(jì)算簽名。這個(gè)路子不是不行但計(jì)算簽名要處理Host、Headers、URL參數(shù)等一系列細(xì)節(jié)一旦某個(gè)地方編碼格式不對(duì)排查起來(lái)特別費(fèi)勁。而且密鑰還是得找個(gè)地方存。相比之下用官方SDK配合STS臨時(shí)密鑰既安全又省心是我實(shí)測(cè)下來(lái)最穩(wěn)的方案。3. 核心代碼實(shí)現(xiàn)與關(guān)鍵參數(shù)3.1 Upload組件側(cè)的模板與狀態(tài)管理Element-UI的Upload組件默認(rèn)的上傳方式是把自己的action指向一個(gè)后端接口靠組件內(nèi)部封裝的XHR去發(fā)請(qǐng)求。這種方式在走“后端中轉(zhuǎn)”時(shí)確實(shí)簡(jiǎn)單但我們要改成前端直傳COS就沒(méi)有現(xiàn)成的后端接口可以指向了。好在Upload組件提供了http-request這個(gè)配置項(xiàng)可以讓我們完全接管上傳邏輯。我的模板結(jié)構(gòu)大致是這樣寫(xiě)的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有幾個(gè)細(xì)節(jié)值得注意第一action屬性傳一個(gè)#占位因?yàn)閔ttp-request接管之后它會(huì)失效但如果不填組件內(nèi)部校驗(yàn)會(huì)不通過(guò)。第二show-file-list我設(shè)置成了false因?yàn)槟J(rèn)的組件文件列表在直傳場(chǎng)景下不好控制狀態(tài)尤其牽扯到分片上傳時(shí)組件內(nèi)置的進(jìn)度條和實(shí)際的分片進(jìn)度很難對(duì)齊。所以我選擇自己維護(hù)一個(gè)fileList數(shù)組完全掌控每張照片的狀態(tài)。第三limit和on-exceed組合使用可以控制上傳數(shù)量上限acceptimage/*用來(lái)限定文件類型但注意它只是彈窗篩選不是安全校驗(yàn)后端或COS側(cè)最好再做一次校驗(yàn)。3.2 基于http-request接管上傳流程http-request是Upload組件暴露給我們的一個(gè)“完全接管”的入口它接收一個(gè)配置對(duì)象包含file、onSuccess、onError、onProgress等信息。這個(gè)設(shè)計(jì)非常巧妙等于把組件的狀態(tài)回調(diào)機(jī)制完整地交給我們自己控制。我的核心上傳函數(shù)是這樣組織的import COS from cos-js-sdk-v5; let cosInstance null; let taskMap new Map(); // 用于存儲(chǔ)任務(wù)Id便于取消 // 向后端獲取臨時(shí)密鑰 async function getCOSCredentials() { const response await axios.get(/api/cos/sts); const { tmpSecretId, tmpSecretKey, sessionToken, expiredTime } response.data; return { tmpSecretId, tmpSecretKey, sessionToken, expiredTime }; } // 初始化或復(fù)用COS實(shí)例 async function getCOSInstance() { if (cosInstance) return cosInstance; const credentials await getCOSCredentials(); if (!credentials.tmpSecretId || !credentials.tmpSecretKey || !credentials.sessionToken) { throw new Error(獲取臨時(shí)密鑰失敗); } cosInstance new COS({ getAuthorization: (options, callback) { // 每次請(qǐng)求前檢查密鑰是否臨近過(guò)期如果過(guò)期則重新獲取 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; }這里有個(gè)容易踩坑的地方getAuthorization不是只調(diào)用一次的。COS SDK在每次發(fā)請(qǐng)求前都會(huì)調(diào)它一次包括初始化、分片上傳的每一個(gè)分片、完成合并請(qǐng)求等。如果每次都去請(qǐng)求后端拿新的密鑰會(huì)產(chǎn)生大量不必要的請(qǐng)求。所以我做了一個(gè)簡(jiǎn)單的判斷如果密鑰剩余時(shí)間還超過(guò)60秒就直接復(fù)用緩存否則才重新獲取。這個(gè)60秒的提前量是經(jīng)驗(yàn)值給SDK留出網(wǎng)絡(luò)波動(dòng)和時(shí)鐘偏差的空間。接下來(lái)是handleHttpRequest的實(shí)現(xiàn)。Upload組件傳給它的參數(shù)中onProgress等回調(diào)是組件內(nèi)置的但我們自己接管后必須手動(dòng)調(diào)用它們才能讓組件的狀態(tài)機(jī)制繼續(xù)工作。我的做法是讓handleHttpRequest返回一個(gè)帶abort()方法的對(duì)象這樣組件在移除文件或取消上傳時(shí)能主動(dòng)中斷我們正在進(jìn)行的COS上傳任務(wù)。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的文件自動(dòng)分片 }; 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的設(shè)計(jì)需要多花點(diǎn)心思。我直接用uploads/前綴加時(shí)間戳和隨機(jī)數(shù)拼接這樣可以避免中文文件名在URL里出現(xiàn)編碼問(wèn)題也減少同名文件互相覆蓋的風(fēng)險(xiǎn)。如果你有按用戶ID分目錄的需求也可以在Key里加上用戶的標(biāo)識(shí)比如uploads/user_12345/xxxxx.jpg這樣管理起來(lái)更清晰。3.3 進(jìn)度條、文件狀態(tài)與取消機(jī)制自己接管上傳之后進(jìn)度條和文件狀態(tài)必須同步維護(hù)。在我接手這個(gè)項(xiàng)目時(shí)發(fā)現(xiàn)一個(gè)經(jīng)典問(wèn)題Element-UI內(nèi)置的el-upload文件列表有自己的status和percentage字段但直傳COS時(shí)分片上傳的進(jìn)度是COS SDK回調(diào)的兩者很容易對(duì)不上。這時(shí)候有兩種選擇一種是把show-file-list保持為true然后在onProgress回調(diào)里手動(dòng)更新file.percentage字段另一種是像我的模板里那樣完全隱藏內(nèi)置列表自己渲染一個(gè)。我選擇了后者原因有兩個(gè)。第一內(nèi)置列表的樣式定制空間很小加上縮略圖、重試按鈕、取消按鈕都要額外處理不如自己寫(xiě)靈活。第二直傳場(chǎng)景下我們需要展示的進(jìn)度粒度更細(xì)——單個(gè)文件切片數(shù)、整體上傳進(jìn)度、以及失敗后的重試入口這些都是自定義列表更好做。我的fileList數(shù)據(jù)項(xiàng)設(shè)計(jì)為// fileList里的每一項(xiàng) { uid: 唯一標(biāo)識(shí), name: example.jpg, status: uploading | success | error, percent: 0, url: , }onProgress回調(diào)更新percent和statusonSuccess更新url和statusonError只更新status。重試操作就是再次調(diào)用handleHttpRequest里那一整套邏輯。這里有個(gè)小技巧不要把COS的臨時(shí)密鑰和實(shí)例做成全局持久化的因?yàn)槊荑€會(huì)過(guò)期。我實(shí)際寫(xiě)代碼時(shí)會(huì)在組件beforeDestroy鉤子里調(diào)用instance.cancelAll()來(lái)清理未完成的任務(wù)防止頁(yè)面銷毀后COS的回調(diào)還在觸發(fā)Vue組件更新導(dǎo)致控制臺(tái)報(bào)錯(cuò)。3.4 后端STS接口的簡(jiǎn)單示例雖然這篇文章主要講前端但后端的STS接口是整個(gè)鏈路能跑通的前提。我寫(xiě)了一個(gè)簡(jiǎn)化的Node.js示例核心原理是使用騰訊云STS SDK用自己服務(wù)端配置的永久密鑰去換一個(gè)臨時(shí)密鑰。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) { // 這里一定要先校驗(yàn)用戶登錄態(tài)再執(zhí)行以下邏輯 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限制了臨時(shí)密鑰只能操作uploads/目錄下的對(duì)象并且限定來(lái)源IP是當(dāng)前請(qǐng)求的IP地址。這是安全上的一道雙保險(xiǎn)。限制目錄的好處是即使臨時(shí)密鑰被截獲攻擊者也不能遍歷或操作整個(gè)桶里的其他文件。我在線上的COS桶里除了uploads/還存了靜態(tài)資源如果不加這條目錄限制風(fēng)險(xiǎn)會(huì)大很多。4. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄4.1 跨域報(bào)錯(cuò)怎么定位我見(jiàn)過(guò)最多的問(wèn)題就是跨域報(bào)錯(cuò)?，F(xiàn)象是控制臺(tái)報(bào)Access to XMLHttpRequest at https://xxx.cos.ap-guangzhou.myqcloud.com/... from origin http://localhost:8080 has been blocked by CORS policy。很多朋友一看到這個(gè)就蒙了其實(shí)定位思路很清晰先確認(rèn)COS桶的CORS配置里有沒(méi)有包含你當(dāng)前的前端域名再確認(rèn)請(qǐng)求方法是不是都在AllowedMethod里最后確認(rèn)AllowedHeader有沒(méi)有設(shè)成*。有一個(gè)很容易忽略的坑CORS配置修改后瀏覽器和COS的邊緣節(jié)點(diǎn)會(huì)有緩存。也就是說(shuō)你在控制臺(tái)改完規(guī)則立刻回前端刷新頁(yè)面測(cè)試發(fā)現(xiàn)還是報(bào)同樣的錯(cuò)這不一定是沒(méi)改成功可能是緩存還沒(méi)過(guò)期。建議等一兩分鐘再測(cè)或者用無(wú)痕窗口驗(yàn)證。我?guī)状巍案耐隉o(wú)效”的假象最后都是緩存在作怪。4.2 上傳成功但組件狀態(tài)異常這個(gè)問(wèn)題非常典型。表現(xiàn)是COS里文件已經(jīng)傳上去了但頁(yè)面的文件狀態(tài)一直停留在“上傳中”或者進(jìn)度條卡在99%不動(dòng)。排查下來(lái)大部分原因是onProgress回調(diào)里percent字段的取法不對(duì)。COS SDK的onProgress回調(diào)返回的對(duì)象里percent是一個(gè)0到100的整數(shù)也可能帶上小數(shù)而Element-UI的el-progress組件期望的是0到100的數(shù)字。有的版本里可能返回1.0這類浮點(diǎn)數(shù)有的返回0.123這種比例值如果你不統(tǒng)一單位就會(huì)出現(xiàn)“瞬間跳到100%后又回退”的情況。我習(xí)慣在回調(diào)里強(qiáng)制做一次Math.floor(data.percent)確保單位統(tǒng)一。另一個(gè)狀態(tài)異常的來(lái)源是http-request沒(méi)有正確返回abort方法。Element-UI的Upload組件在移除文件時(shí)會(huì)去調(diào)用fileList對(duì)應(yīng)項(xiàng)的XHR對(duì)象的abort方法但自定義上傳時(shí)我們并沒(méi)有真正的XHR對(duì)象組件只能調(diào)用我們返回的對(duì)象上的abort。如果不返回這個(gè)方法移除文件時(shí)組件會(huì)報(bào)錯(cuò)或者干脆沒(méi)反應(yīng)。4.3 簽名過(guò)期與并發(fā)問(wèn)題簽名過(guò)期是另一個(gè)高頻坑。最典型的場(chǎng)景是用戶打開(kāi)上傳頁(yè)面超過(guò)半小時(shí)才開(kāi)始選文件或者批量上傳大文件時(shí)傳了一半密鑰過(guò)期了。前者可以通過(guò)在getAuthorization里檢查過(guò)期時(shí)間解決后者則更麻煩因?yàn)槊荑€的刷新時(shí)機(jī)正好落在分片上傳的中間——某個(gè)分片用舊密鑰在傳下一個(gè)分片已經(jīng)開(kāi)始請(qǐng)求新密鑰了這種并發(fā)狀態(tài)下偶爾會(huì)出現(xiàn)400或403異常。我的解決方案是給密鑰刷新加一個(gè)互斥鎖。用簡(jiǎn)單的Promise鏈讓并發(fā)請(qǐng)求等待同一個(gè)刷新操作完成避免多個(gè)分片同時(shí)觸發(fā)多次STS請(qǐng)求。具體實(shí)現(xiàn)可以是let credentialPromise null; function requestCredentials() { if (!credentialPromise) { credentialPromise getCOSCredentials() .then(data { credentialPromise null; return data; }) .catch(error { credentialPromise null; throw error; }); } return credentialPromise; }這樣即使幾十個(gè)分片同時(shí)需要新密鑰也只有一個(gè)真正的STS請(qǐng)求在飛其余的全部復(fù)用同一個(gè)Promise的返回值。這個(gè)模式不只是COS上傳可以用任何前端“一次性初始化”的異步資源比如SDK加載、token獲取都適用。4.4 分片大小與并發(fā)參數(shù)的選擇SliceSize參數(shù)決定了上傳時(shí)是否啟用分片以及分片的大小。我實(shí)測(cè)下來(lái)的經(jīng)驗(yàn)是對(duì)于普通圖片把SliceSize設(shè)為5MB即可對(duì)于幾百M(fèi)B的視頻分片大小可以提高到10MB甚至20MB減少分片數(shù)量降低合并請(qǐng)求的壓力。分片太小會(huì)導(dǎo)致發(fā)起大量HTTP請(qǐng)求性能反而下降太大則失去分片上傳的斷點(diǎn)續(xù)傳優(yōu)勢(shì)。COS SDK內(nèi)部對(duì)分片上傳的并發(fā)數(shù)也有默認(rèn)值通常不需要手動(dòng)調(diào)。但如果你的用戶普遍網(wǎng)絡(luò)帶寬很高可以適當(dāng)調(diào)高并發(fā)數(shù)來(lái)加速上傳如果網(wǎng)絡(luò)質(zhì)量不穩(wěn)定反而應(yīng)該降低并發(fā)數(shù)減少單個(gè)分片失敗導(dǎo)致整個(gè)上傳失敗的概率。我一般是先按默認(rèn)值跑然后在監(jiān)控后臺(tái)觀察上傳耗時(shí)和失敗率再微調(diào)。5. 其他注意事項(xiàng)與補(bǔ)充5.1 完整的文件校驗(yàn)流程直傳模式下前端的文件校驗(yàn)不能只靠accept屬性。我在beforeUpload里會(huì)做以下檢查文件大小是否超過(guò)限制、文件類型是否符合白名單、文件名后綴是否在允許列表中。COS SDK雖然會(huì)做服務(wù)端的校驗(yàn)但如果前端能把明顯不合法的請(qǐng)求攔截下來(lái)既減少無(wú)效上傳也避免用戶被莫名其妙的錯(cuò)誤提示困擾。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(文件大小不能超過(guò)20MB); return false; } if (WHITE_LIST.indexOf(file.type) -1) { this.$message.error(僅支持jpg、png、gif、webp格式); return false; } return true; }注意file.type在部分瀏覽器里可能為空字符串尤其是某些壓縮包或者特殊格式圖片。所以不能完全依賴MIME類型要同時(shí)保留后綴名的判斷邏輯兩種校驗(yàn)雙保險(xiǎn)。5.2 隱私與安全的幾個(gè)小建議前端直傳COS雖然把存儲(chǔ)壓力轉(zhuǎn)移到了云端但安全問(wèn)題不能忽視。除了前面提到的STS臨時(shí)密鑰、目錄權(quán)限限定之外我還建議在COS控制臺(tái)開(kāi)啟防盜鏈限制Referer來(lái)源域名防止他人盜用圖片鏈接。另外私有讀寫(xiě)的桶要配合生成臨時(shí)URL供前端顯示縮略圖這時(shí)候可以用COS SDK的getObjectUrl方法生成帶簽名、帶有效期的訪問(wèn)地址。還有一個(gè)經(jīng)常被忽略的點(diǎn)上傳完成后業(yè)務(wù)后端最好通過(guò)COS的事件通知或回調(diào)接口做二次確認(rèn)。也就是說(shuō)前端告訴后端“我傳成功了”后端可以再調(diào)COS API驗(yàn)證這個(gè)文件確實(shí)存在并且校驗(yàn)它的大小、類型是否和預(yù)期一致。這樣能防止前端偽造上傳成功的信息在安全級(jí)別要求高的業(yè)務(wù)里很有必要。5.3 后續(xù)擴(kuò)展方向這個(gè)方案跑通之后可以擴(kuò)展的點(diǎn)其實(shí)很多。比如結(jié)合COS的圖片處理API在上傳完成后生成不同尺寸的縮略圖或者把上傳記錄寫(xiě)入數(shù)據(jù)庫(kù)做成一個(gè)完整的“附件中心”再或者加上相似度檢查、圖片審核功能。對(duì)我自己來(lái)說(shuō)最實(shí)用的是把上傳回調(diào)里生成的URL直接回填到表單數(shù)據(jù)里整個(gè)流程就順暢閉環(huán)了。最后再分享一個(gè)我調(diào)試時(shí)覺(jué)得特別好用的技巧在開(kāi)發(fā)環(huán)境下可以用Vue的mixin全局注入一個(gè)調(diào)試開(kāi)關(guān)當(dāng)?debugcos出現(xiàn)在URL里時(shí)把COS SDK每次請(qǐng)求的requestId、statusCode、taskId都打印到控制臺(tái)。這樣在線上定位問(wèn)題的時(shí)候只要讓用戶帶上這個(gè)參數(shù)訪問(wèn)就能拿到完整的上傳鏈路日志比自己猜要高效得多。這個(gè)習(xí)慣幫我省了無(wú)數(shù)次遠(yuǎn)程排查的時(shí)間也算是一個(gè)值得留存的小工具。