前端文件上传实战：从基础校验到分块上传

前言

文件上传看似简单，实则暗藏玄机。很多开发者以为加个 <input type="file"> 就能搞定，结果遇到大文件就崩溃，或者用户根本不知道上传进度。作为前端工程师，我们需要在用户体验、性能优化和安全性之间找到平衡。

常见误区

在实际项目中，我们常看到一些粗糙的实现方式，它们往往埋下了隐患。

• 缺乏校验：直接提交文件，导致服务器接收恶意文件或超大文件，造成资源浪费。
• 忽略类型限制：允许上传任意格式，可能带来安全风险。
• 无进度反馈：用户点击上传后只能干等，体验极差。
• 错误处理缺失：网络波动或失败时，没有提示，用户无从得知原因。

下面是一个典型的反面教材，展示了这些问题的集中体现：

// 简单的上传逻辑，缺少验证和错误处理
function uploadFile() {
  const fileInput = document.getElementById('fileInput');
  const file = fileInput.files[0];
  const formData = new FormData();
  formData.append('file', file);
  fetch('/api/upload', {
    method: 'POST',
    body: formData
  })
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error(error)); // 仅打印日志，未提示用户
}

核心实现方案

1. 基础校验与单文件上传

在发送请求前，务必在前端进行基础校验。这不仅能减轻服务器压力，还能给用户即时反馈。

function uploadFile() {
  const fileInput = document.getElementById('fileInput');
  const file = fileInput.files[0];

  if (!file) return;

  // 校验文件大小 (例如限制 10MB)
  if (file.size > 10 * 1024 * 1024) {
    alert('文件过大，请上传小于 10MB 的文件');
    return;
  }

  // 校验文件类型
  const allowedTypes = ['image/jpeg', 'image/png', 'image/gif'];
  if (!allowedTypes.includes(file.type)) {
    alert('不支持该文件格式');
    return;
  }

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

  fetch('/api/upload', {
    method: 'POST',
    body: formData
  })
  .then(response => {
    if (!response.ok) throw new Error('Upload failed');
    return response.json();
  })
  .then(data => {
    console.log('上传成功:', data);
    alert('文件上传成功');
  })
  .catch(error => {
    console.error('上传错误:', error);
    alert('上传失败：' + error.message);
  });
}

2. 多文件上传

支持批量选择是基本需求。注意 FormData 的键名设置，后端通常期望数组形式。

function uploadFiles() {
  const fileInput = document.getElementById('fileInput');
  const files = fileInput.files;

  if (files.length === 0) {
    alert('请选择文件');
    return;
  }

  for (const file of files) {
    if (file.size > 10 * 1024 * 1024) {
      alert(`文件 ${file.name} 过大`);
      return;
    }
  }

  const formData = new FormData();
  for (const file of files) {
    formData.append('files', file); // 注意键名匹配后端
  }

  fetch('/api/upload-multiple', {
    method: 'POST',
    body: formData
  })
  .then(response => response.json())
  .then(data => alert('批量上传成功'))
  .catch(error => alert('上传失败')); 
}

3. 上传进度显示

这里有个技术细节：标准的 Fetch API 并不支持上传进度监听。如果需要精确的进度条，必须使用 XMLHttpRequest。

function uploadFileWithProgress() {
  const fileInput = document.getElementById('fileInput');
  const progressBar = document.getElementById('progressBar');
  const file = fileInput.files[0];

  if (!file) return;

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

  const xhr = new XMLHttpRequest();

  // 监听上传进度
  xhr.upload.addEventListener('progress', function(event) {
    if (event.lengthComputable) {
      const percentCompleted = Math.round((event.loaded * 100) / event.total);
      progressBar.style.width = percentCompleted + '%';
      progressBar.textContent = percentCompleted + '%';
    }
  });

  // 监听完成状态
  xhr.addEventListener('load', function() {
    if (xhr.status === 200) {
      const data = JSON.parse(xhr.responseText);
      console.log('上传成功:', data);
      alert('文件上传成功');
    } else {
      alert('上传失败：' + xhr.statusText);
    }
  });

  xhr.addEventListener('error', function() {
    alert('网络错误');
  });

  xhr.open('POST', '/api/upload');
  xhr.send(formData);
}

4. 拖拽上传

提升交互体验的关键一步。需要阻止浏览器的默认行为（如打开文件），并监听相关事件。

function setupDragAndDrop() {
  const dropArea = document.getElementById('dropArea');

  dropArea.addEventListener('dragover', function(event) {
    event.preventDefault();
    dropArea.classList.add('drag-over');
  });

  dropArea.addEventListener('dragleave', function() {
    dropArea.classList.remove('drag-over');
  });

  dropArea.addEventListener('drop', function(event) {
    event.preventDefault();
    dropArea.classList.remove('drag-over');
    const files = event.dataTransfer.files;
    if (files.length > 0) {
      uploadFiles(files);
    }
  });

  // 兼容点击上传
  dropArea.addEventListener('click', function() {
    document.getElementById('fileInput').click();
  });
}

5. 大文件分块上传

对于超过 100MB 的文件，一次性上传容易超时或失败。分块上传是标准解决方案。

async function uploadLargeFile(file) {
  const chunkSize = 1024 * 1024; // 1MB
  const totalChunks = Math.ceil(file.size / chunkSize);
  const fileId = generateFileId();

  for (let i = 0; i < totalChunks; i++) {
    const start = i * chunkSize;
    const end = Math.min(start + chunkSize, file.size);
    const chunk = file.slice(start, end);

    const formData = new FormData();
    formData.append('file', chunk);
    formData.append('fileId', fileId);
    formData.append('chunkIndex', i);
    formData.append('totalChunks', totalChunks);

    try {
      const response = await fetch('/api/upload-chunk', {
        method: 'POST',
        body: formData
      });
      if (!response.ok) throw new Error('Chunk upload failed');
    } catch (error) {
      console.error('分片上传失败:', error);
      throw error;
    }
  }

  // 通知服务器合并分片
  const mergeResponse = await fetch('/api/merge-chunks', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ fileId, fileName: file.name, totalChunks })
  });

  if (!mergeResponse.ok) throw new Error('Merge failed');
  return mergeResponse.json();
}

function generateFileId() {
  return Math.random().toString(36).substring(2, 15) + Math.random().toString(36).substring(2, 15);
}

进阶最佳实践

除了基础功能，生产环境还需要考虑图片预览、压缩以及状态管理。

图片预览与压缩

利用 FileReader 和 Canvas 可以在上传前预览并压缩图片，减少流量消耗。

function compressImage(file, maxWidth = 800, maxHeight = 800, quality = 0.8) {
  return new Promise((resolve) => {
    const canvas = document.createElement('canvas');
    const ctx = canvas.getContext('2d');
    const img = new Image();
    img.onload = function() {
      let width = img.width;
      let height = img.height;
      if (width > height) {
        if (width > maxWidth) { height = (height * maxWidth) / width; width = maxWidth; }
      } else {
        if (height > maxHeight) { width = (width * maxHeight) / height; height = maxHeight; }
      }
      canvas.width = width;
      canvas.height = height;
      ctx.drawImage(img, 0, 0, width, height);
      canvas.toBlob(function(blob) { resolve(blob); }, file.type, quality);
    };
    img.src = URL.createObjectURL(file);
  });
}

安全验证

不要完全信任前端校验，但前端校验能拦截大部分无效请求。同时建议校验文件扩展名。

function validateFile(file) {
  if (file.size > 10 * 1024 * 1024) return { valid: false, message: 'File too large' };
  const allowedTypes = ['image/jpeg', 'image/png', 'image/gif', 'application/pdf'];
  if (!allowedTypes.includes(file.type)) return { valid: false, message: 'Invalid type' };
  const extension = file.name.substring(file.name.lastIndexOf('.'));
  const allowedExtensions = ['.jpg', '.png', '.pdf'];
  if (!allowedExtensions.includes(extension.toLowerCase())) return { valid: false, message: 'Invalid extension' };
  return { valid: true, message: 'Valid' };
}

上传状态管理

当有多个任务并发时，需要一个管理器来维护状态。

class UploadManager {
  constructor() {
    this.uploads = new Map();
  }
  async upload(file) {
    const id = generateFileId();
    const upload = { id, file, status: 'pending', progress: 0, error: null };
    this.uploads.set(id, upload);
    try {
      upload.status = 'uploading';
      // 调用实际上传逻辑...
      upload.status = 'completed';
      upload.progress = 100;
    } catch (error) {
      upload.status = 'failed';
      upload.error = error.message;
    }
    return upload;
  }
  cancelUpload(id) {
    const upload = this.uploads.get(id);
    if (upload) upload.status = 'cancelled';
  }
}

总结与建议

文件上传的核心目的是方便用户，而不是炫技。实现方案的选择应基于实际需求：

1. 小文件：直接使用 FormData + Fetch 即可，无需过度设计。
2. 大文件：必须引入分块上传和断点续传机制。
3. 进度反馈：Fetch 无法提供上传进度，需回退到 XMLHttpRequest。
4. 安全性：前端校验只是第一道防线，后端必须再次严格校验。

避免为了追求功能全面而引入复杂的第三方库，保持代码的可维护性同样重要。如果项目不需要分块上传，就不要强行上分块，否则只会增加不必要的复杂度。记住，好的技术实现应该是隐形的，让用户感觉不到它的存在，只觉得好用。