📝 大文件上傳前端設計文檔

一、方案概述與設計依據

1.1 設計目標

基於文件分塊和斷點續傳機制，實現高效、穩定、可恢復的大文件上傳功能，解決傳統上傳模式下大文件易失敗的問題。

1.2 核心流程（圖示解析）

環節

核心目標

關鍵技術

前端拆分文件

將大文件切分為可控的小塊，並建立唯一身份標識。

File.prototype.slice()，Web Worker 計算 MD5。

分片校驗與上傳

利用標識符查詢已完成分片，實現秒傳和續傳。

預檢請求，併發控制。

後端接收與合併

保證所有分片完整，通知後端合併。

後端接口設計（合併通知）。

異常處理

保證上傳任務的完整性和用户體驗。

斷點續傳邏輯，AbortController。

二、前端詳細實現流程

2.1 環節一：前端拆分文件（準備階段）

這是上傳任務的啓動階段，核心是將大文件轉化為可管理的上傳單元，並賦予其唯一標識。

1. 文件分片
  • API 使用： 採用瀏覽器原生的 File.prototype.slice() 方法。
  • 分片大小： 固定為 5MB（需根據服務器性能調整），將 File 對象切分成 Blob 數組。
  • 分片信息： 每個分片（Chunk）對象應包含：
  • chunkIndex: 分片索引（從 0 開始）。
  • chunkTotal: 文件總分片數。
  • chunkBlob: 實際的二進制數據塊。
2. 文件唯一標識（MD5）
  • 唯一標識： 計算整個文件的 MD5 值 (fileHash) 作為文件的全局唯一 ID。
  • 性能優化（關鍵）： MD5 計算是 CPU 密集型操作，為避免瀏覽器主線程阻塞，必須在 Web Worker 線程中進行計算。
  • 數據流向： fileHash 將貫穿整個上傳過程，作為後端識別文件身份的依據。

2.2 環節二：分片校驗與上傳（核心階段）

通過 fileHash 預先與後端通信，確定上傳起點，並以併發方式高效傳輸數據。

1. 分片校驗與續傳查詢
  • 預檢請求： 在正式上傳前，前端向後端發送一個校驗請求：
  • POST /upload/verify 攜帶 fileHash、fileSize、fileName。
  • 後端響應處理：
  • 秒傳成功（例如 200）： 文件已存在，通知用户完成上傳。
  • 需繼續上傳（例如 201）： 後端返回已完成的分片索引列表（[0, 1, 5, ...]）。
  • 待傳隊列生成： 前端根據總分片數和後端返回的列表，過濾掉已完成的分片，生成待上傳的分片隊列。
2. 併發請求上傳
  • 併發控制： 使用 Promise 隊列 或 異步任務限制工具，將併發數限制在合理範圍（如 3-6），防止瞬時網絡擁塞。
  • 請求封裝： 每個分片使用 FormData 封裝，通過 POST 請求發送到 /upload/chunk 接口。
  • 數據驗證： 請求中包含 fileHash、chunkIndex、chunkTotal，確保後端能正確接收和暫存分片。

2.3 環節三：後端接收與合併（收尾階段）

當前端待上傳隊列清空（所有分片上傳成功）時，進入收尾階段。

1. 合併通知
  • 觸發時機： 最後一個分片上傳成功後。
  • 請求通知： 前端發送文件合併請求：POST /upload/merge，攜帶 fileHash 和 chunksTotal。
  • 後端處理： 後端接收通知後，根據 fileHash 找到所有暫存的分片，按 chunkIndex 順序合併成完整文件，並清理臨時分片存儲空間。

三、異常處理機制

強大的異常處理能力是實現斷點續傳和穩定上傳的關鍵。

3.1 斷點續傳（Resume Upload）

  • 實現機制： 完全依賴於後端的狀態。
  • 觸發場景： 用户刷新頁面、瀏覽器崩潰後重新打開、或上傳任務主動暫停後恢復。
  • 處理流程： 在任何需要恢復上傳的場景，始終重新執行 “分片校驗與續傳查詢” 的預檢請求，獲取最新的已上傳分片列表，重新生成待傳隊列並繼續上傳。

3.2 失敗重傳（Retry Mechanism）

  • 觸發場景： 單個分片請求因網絡波動、超時或服務器臨時錯誤而失敗。
  • 處理邏輯：
  1. 檢測到分片上傳失敗（非 200 狀態碼）。
  2. 將該分片重新加入待上傳隊列，自動重試 N 次（推薦 N=3）。
  3. 如果重試 N 次後仍然失敗，則暫停整個上傳任務，並向用户展示明確的錯誤信息。

3.3 上傳暫停和取消

1. 暫停上傳
  • 前端操作： 使用瀏覽器原生的 AbortController API 終止所有正在進行的 fetch 或 XMLHttpRequest 請求。
  • 狀態維護： 暫停後，當前已完成的分片信息已保留在後端，等待用户點擊“恢復”時進行斷點續傳。
2. 取消上傳
  • 前端操作： 終止所有正在進行的請求。
  • 後端通知： 向後端發送 清理請求（例如 DELETE /upload/abort 攜帶 fileHash），通知後端刪除所有已暫存的分片數據，徹底釋放服務器空間。

四、前端優化與用户體驗

優化點

目標

備註

實時進度條

實時反饋上傳進度。

總進度條應基於 已完成分片數/總分片數 計算。

錯誤提示

明確告知用户問題所在。

失敗時應區分是網絡問題、文件問題還是服務器問題。

資源清理

優化內存使用。

當一個分片上傳成功後，可以考慮釋放該分片對應的 Blob 對象在前端的引用。

併發數調整

適應不同網絡環境。

允許用户在設置中調整併發數，或根據用户帶寬動態調整。