文件上传与管理

概述

文件上传是 Web 应用中最常见的功能之一，但实现一个健壮、用户体验良好的上传模块涉及诸多技术细节：分片上传、断点续传、秒传、进度追踪、并发控制、文件预览等。本文将深入解析文件上传的技术原理与工程实践，帮助你构建企业级的文件管理方案。

---

一、上传库的封装与使用

1.1 主流上传库对比

在前端生态中，以下上传库被广泛使用：

库	特点	适用场景
Uppy	模块化、插件丰富、支持多种后端	通用 Web 应用
Plupload	支持 Flash/Silverlight/HTML5 多运行时	兼容老旧浏览器
axios + 原生 XHR	轻量、灵活、可控性强	自定义上传逻辑
FilePond	美观的 UI 组件、拖拽上传	注重 UI 体验的应用

1.2 Uppy 基础封装示例

import Uppy from '@uppy/core'
import Dashboard from '@uppy/dashboard'
import XHRUpload from '@uppy/xhr-upload'

const uppy = new Uppy({
  restrictions: {
    maxFileSize: 50 * 1024 * 1024,  // 50MB
    maxNumberOfFiles: 10,
    allowedFileTypes: ['.jpg', '.png', '.pdf', '.docx'],
  },
})

uppy.use(Dashboard, {
  target: '#upload-container',
  inline: true,
  showProgressDetails: true,
})

uppy.use(XHRUpload, {
  endpoint: '/api/upload',
  method: 'POST',
  formData: true,
  fieldName: 'file',
})

1.3 原生 XMLHttpRequest 封装

对于需要精细控制的场景，封装原生 XHR 是最灵活的方式：

class FileUploader {
  constructor(options) {
    this.url = options.url
    this.onProgress = options.onProgress
    this.onComplete = options.onComplete
    this.onError = options.onError
    this.xhr = new XMLHttpRequest()
  }

  upload(file) {
    const formData = new FormData()
    formData.append('file', file)

    this.xhr.upload.addEventListener('progress', (e) => {
      if (e.lengthComputable) {
        const percent = Math.round((e.loaded / e.total) * 100)
        this.onProgress?.(percent, e.loaded, e.total)
      }
    })

    this.xhr.addEventListener('load', () => {
      if (this.xhr.status >= 200 && this.xhr.status < 300) {
        this.onComplete?.(this.xhr.responseText)
      } else {
        this.onError?.(new Error(`Upload failed: ${this.xhr.status}`))
      }
    })

    this.xhr.open('POST', this.url)
    this.xhr.send(formData)
  }

  abort() {
    this.xhr.abort()
  }
}

---

二、分片上传原理与实现

2.1 为什么需要分片上传

大文件上传面临以下问题：

1. HTTP 连接超时：单次上传大文件可能超过服务器超时时间
2. 失败重试成本高：一个 1GB 文件上传到 99% 失败，需从头重传
3. 并发限制：浏览器对单域名并发连接数有限制
4. 内存占用：大文件一次性读入内存可能导致浏览器崩溃

分片上传将大文件切分成多个小片段，分别上传，有效解决了上述问题。

2.2 核心实现

const CHUNK_SIZE = 5 * 1024 * 1024  // 5MB 每片

async function uploadInChunks(file, uploadUrl, onProgress) {
  const totalChunks = Math.ceil(file.size / CHUNK_SIZE)
  const fileId = generateFileId(file)  // 文件唯一标识
  
  for (let i = 0; i < totalChunks; i++) {
    const start = i * CHUNK_SIZE
    const end = Math.min(start + CHUNK_SIZE, file.size)
    const chunk = file.slice(start, end)
    
    const formData = new FormData()
    formData.append('file', chunk)
    formData.append('chunkIndex', i)
    formData.append('totalChunks', totalChunks)
    formData.append('fileId', fileId)
    
    // 带重试的上传
    let retries = 3
    while (retries > 0) {
      try {
        await uploadChunk(formData, uploadUrl)
        break
      } catch (err) {
        retries--
        if (retries === 0) throw err
        await delay(1000)  // 重试等待
      }
    }
    
    const percent = Math.round(((i + 1) / totalChunks) * 100)
    onProgress?.(percent)
  }
  
  // 通知服务端合并分片
  await mergeChunks(fileId, file.name, totalChunks)
}

2.3 并发控制

分片上传时，控制并发数能充分利用带宽，同时避免压垮服务器：

async function uploadWithConcurrency(chunks, maxConcurrency = 3) {
  const results = []
  const queue = [...chunks]
  
  async function worker() {
    while (queue.length > 0) {
      const chunk = queue.shift()
      const result = await uploadChunk(chunk)
      results.push(result)
    }
  }
  
  const workers = Array.from({ length: maxConcurrency }, () => worker())
  await Promise.all(workers)
  return results
}

2.4 进度计算

准确的进度计算需要综合考虑已上传分片和当前上传分片的进展：

function calculateProgress(chunks, currentIndex, currentChunkProgress) {
  const totalChunks = chunks.length
  const completedChunks = currentIndex  // 已完成的完整分片数

  // 已完成部分占比 + 当前分片部分占比
  return (completedChunks / totalChunks) + 
         (currentChunkProgress / 100) * (1 / totalChunks)
}

---

三、秒传机制

3.1 原理

秒传的核心思想是：上传前先检查文件是否已存在于服务器。如果存在，客户端无需真正上传，直接标记为上传成功。

3.2 文件哈希预检

通过文件内容的哈希值（如 MD5、SHA-256）作为文件的唯一标识：

async function computeFileHash(file) {
  // 使用浏览器原生 Crypto API 计算 SHA-256
  const buffer = await file.arrayBuffer()
  const hashBuffer = await crypto.subtle.digest('SHA-256', buffer)
  const hashArray = Array.from(new Uint8Array(hashBuffer))
  return hashArray.map(b => b.toString(16).padStart(2, '0')).join('')
}

async function checkFileExists(file) {
  const fileHash = await computeFileHash(file)
  const response = await fetch(`/api/check-file?hash=${fileHash}`)
  const data = await response.json()
  
  if (data.exists) {
    // 秒传：无需上传，直接使用已有文件
    console.log('文件已存在，秒传成功！')
    return { exists: true, url: data.url }
  }
  
  return { exists: false }
}

3.3 大文件快速哈希

对于大文件，计算完整哈希耗时较长。可以使用 增量哈希 策略：

• 快速预检：使用文件大小 + 文件名 + 前 1MB 内容计算哈希
• 精确匹配：快速预检通过后，再计算完整哈希确认
• 抽样哈希：间隔读取文件的多个片段计算组合哈希

async function quickHash(file) {
  const head = await file.slice(0, 1024 * 1024).arrayBuffer()
  const headHash = await crypto.subtle.digest('SHA-256', head)
  // 结合文件大小和最后修改时间
  return `${file.size}-${file.lastModified}-${bufToHex(headHash)}`
}

---

四、文件预览方案

4.1 图片预览

function previewImage(file) {
  return new Promise((resolve) => {
    const reader = new FileReader()
    reader.onload = (e) => resolve(e.target.result)
    reader.readAsDataURL(file)
  })
}

// 缩略图生成（限制最大尺寸）
function createThumbnail(file, maxSize = 200) {
  return new Promise((resolve) => {
    const img = new Image()
    img.onload = () => {
      const canvas = document.createElement('canvas')
      const scale = Math.min(maxSize / img.width, maxSize / img.height, 1)
      canvas.width = img.width * scale
      canvas.height = img.height * scale
      const ctx = canvas.getContext('2d')
      ctx.drawImage(img, 0, 0, canvas.width, canvas.height)
      resolve(canvas.toDataURL('image/jpeg', 0.8))
    }
    img.src = URL.createObjectURL(file)
  })
}

4.2 其他文件类型预览

文件类型	预览方案
图片	<img> + FileReader / URL.createObjectURL
视频	<video> + URL.createObjectURL
音频	<audio> + URL.createObjectURL
PDF	PDF.js 渲染或 <iframe> 直接预览
文本/代码	FileReader 读为文本后在 <pre> 中展示
Office 文档	使用 Office Online / Google Docs Viewer 等第三方服务
压缩包	显示文件列表（需后端解压分析）

4.3 大图渐进加载

对于超大图片（如 5000px+ 宽），直接加载到 DOM 可能导致性能问题。可以采用以下策略：

• 缩略图优先：先展示低分辨率缩略图
• 瓦片加载：将大图切割为多个瓦片，按需加载可视区域
• WebP/AVIF 格式：使用更高压缩率的图片格式

---

五、拖拽上传

5.1 HTML5 Drag & Drop API

const dropZone = document.getElementById('drop-zone')

dropZone.addEventListener('dragover', (e) => {
  e.preventDefault()
  dropZone.classList.add('dragover')
})

dropZone.addEventListener('dragleave', () => {
  dropZone.classList.remove('dragover')
})

dropZone.addEventListener('drop', (e) => {
  e.preventDefault()
  dropZone.classList.remove('dragover')
  
  const files = Array.from(e.dataTransfer.files)
  handleFiles(files)
})

5.2 文件夹上传

HTML5 的 webkitGetAsEntry API 支持递归读取文件夹结构：

async function traverseDirectory(entry) {
  const files = []
  
  async function readEntry(entry, path = '') {
    if (entry.isFile) {
      const file = await new Promise((resolve) => entry.file(resolve))
      file.relativePath = path + file.name
      files.push(file)
    } else if (entry.isDirectory) {
      const reader = entry.createReader()
      const entries = await new Promise((resolve) => reader.readEntries(resolve))
      for (const child of entries) {
        await readEntry(child, path + entry.name + '/')
      }
    }
  }
  
  await readEntry(entry)
  return files
}

5.3 拖拽反馈与视觉优化

良好的拖拽反馈能显著提升用户体验：

• 拖拽悬停动画：边框高亮、背景色变化
• 文件数量提示：显示本次拖入了多少个文件
• 格式验证提示：拖入不支持的文件格式时，给出视觉警告
• 释放动画：文件释放后，列表项优雅地滑入

---

六、综合实践方案

6.1 完整上传流程

用户选择文件
     │
     ▼
文件格式/大小校验 ──── 不合法 ──→ 提示错误
     │ 合法
     ▼
计算文件哈希
     │
     ▼
发送预检请求 ──── 文件已存在 ──→ 秒传成功（直接返回URL）
     │ 不存在
     ▼
大文件判断 ──── 小于阈值 ──→ 单次上传
     │ 大于阈值
     ▼
分片上传（并发控制 3~5）
     │
     ▼
所有分片完成 ────→ 通知合并 ────→ 上传完成

6.2 错误处理策略

错误类型	处理策略
网络中断	自动重试（3 次），指数退避
上传超时	增加超时时间，分片大小减半重试
服务端错误	根据 HTTP 状态码区分处理
文件校验失败	重新上传对应分片

6.3 性能优化建议

1. 分片大小：推荐 1MB~10MB，过小导致请求过多，过大失去分片优势
2. 并发数：3~5 个并发通常是最佳平衡点
3. 使用 Web Worker：将哈希计算放在 Worker 中，避免阻塞主线程
4. 请求池复用：使用 HTTP/2 多路复用减少连接开销
5. 本地缓存：已上传的分片信息存储在 IndexedDB 中，支持断点续传

---

七、交互演示

以下 Demo 展示了一个完整的文件管理器，支持拖拽上传、分片上传动画、文件预览等功能：