COS 前端直傳工具與檔案操作示例

一句話介紹

基於騰訊雲 COS 的完整檔案上傳解決方案，提供後端 API 直傳與前端 STS 臨時密鑰直傳兩種接入模式，並附帶 Next.js 前端範例。

項目定位

本項目為需接入騰訊雲物件儲存（COS）的專案提供開箱即用的上傳方案。透過 FastAPI 後端封裝 COS 操作，同時提供 STS 臨時密鑰生成介面，讓前端可直接將檔案上傳至 COS，無需經由後端中轉，從而降低伺服器頻寬負擔。

主要功能

1. 後端 API 上傳

透過 FastAPI 後端介面將檔案上傳至 COS，適合小檔案及服務端場景。

功能特性：

• POST /upload 一鍵上傳
• 自動按年／月建立資料夾儲存
• 回傳 COS 存取 URL
• 支援多組 API Key 對應多個儲存桶（Bucket）

2. 前端 STS 直傳

瀏覽器端取得臨時密鑰後，直接上傳至 COS，適合大檔案與高併發場景。

直傳優勢：

• 檔案不經過後端中轉
• STS 臨時密鑰安全且可控
• 支援分段上傳（Multipart Upload）
• 權限限定於指定目錄
• 附帶 cos-js-sdk-v5 的 Next.js 前端範例

3. 多儲存桶與多密鑰管理

支援設定多個 COS 儲存桶及其對應的 API Key，靈活適配不同專案需求。

映射規則：

• API_KEY → COS_BUCKET + COS_REGION
• API_KEY_2 → COS_BUCKET_2 + COS_REGION_2
• 支援無限擴展
• 區域設定可回退至全域預設值

4. CORS 與網頁介面

內建 CORS 設定與網頁上傳介面，開箱即用。

介面功能：

• HTML 上傳頁面
• 支援拖曳上傳
• 顯示上傳進度
• 一鍵複製檔案 URL

應用場景

前端專案檔案上傳

為 Next.js、React 等前端專案提供即插即用的 COS 直傳方案。

多專案共用上傳服務

單一後端服務管理多個 COS 儲存桶，不同專案透過不同 API Key 接入。

大檔案上傳場景

善用 STS 直傳與分段上傳能力，處理影片、壓縮檔等大型檔案。

快速原型開發

作為新專案的檔案上傳基礎設施，快速搭建，無需從零配置。

產品價值

• 兩種上傳模式涵蓋不同業務需求
• STS 直傳大幅降低後端頻寬壓力
• 多儲存桶管理靈活支援多專案部署
• 附完整前端範例，顯著降低接入門檻
• 提供 PM2 部署設定，支援生產環境