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