基于 Axios 的前端文件上传下载实战指南

进阶版：多文件上传

多文件上传只需循环 append。注意同一字段名多次添加时，后端框架（如 SpringBoot 或 Multer）通常能接收为数组。

const uploadMultipleFiles = async (fileList) => {
  const formData = new FormData();
  fileList.forEach((file, index) => {
    formData.append('files', file);
    formData.append(`fileNames[${index}]`, file.name);
  });

  try {
    const response = await axios.post('/api/upload/batch', formData,
      { headers: { 'Content-Type': undefined } }
    );
    return response.data;
  } catch (error) {
    console.error('批量上传失败:', error);
    throw error;
  }
};

带进度条的上传

利用 onUploadProgress 回调监听 XMLHttpRequest 的 progress 事件，可实时反馈上传状态。

const uploadWithProgress = (file, onProgress) => {
  const formData = new FormData();
  formData.append('file', file);
  
  return axios.post('/api/upload', formData, {
    headers: { 'Content-Type': undefined },
    onUploadProgress: (progressEvent) => {
      const percentCompleted = Math.round((progressEvent.loaded * 100) / progressEvent.total);
      if (onProgress) onProgress(percentCompleted);
    },
    timeout: 0 // 大文件建议延长超时时间
  });
};

下载文件实战

下载的关键在于设置 responseType: 'blob'，否则 Axios 会尝试将响应解析为 JSON 字符串。

基础下载与文件名处理

正确的下载流程包括获取 Blob、创建临时链接、触发点击及清理 URL。

const downloadExcel = async () => {
  try {
    const response = await axios({
      url: '/api/export/user-list',
      method: 'GET',
      responseType: 'blob',
      params: { startDate: '2024-01-01', endDate: '2024-12-31' }
    });

    // 提取文件名
    const contentDisposition = response.headers['content-disposition'];
    let fileName = '用户列表.xlsx';
    if (contentDisposition) {
      const utf8Match = contentDisposition.match(/filename\*=UTF-8''([^;]+)/i);
      if (utf8Match && utf8Match[1]) {
        fileName = decodeURIComponent(utf8Match[1]);
      } else {
        const normalMatch = contentDisposition.match(/filename="([^"]+)"/i);
        if (normalMatch && normalMatch[1]) fileName = normalMatch[1];
      }
    }

    const blob = new Blob([response.data], {
      type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
    });
    const url = window.URL.createObjectURL(blob);
    const link = document.createElement('a');
    link.href = url;
    link.download = fileName;
    document.body.appendChild(link);
    link.click();
    document.body.removeChild(link);
    window.URL.revokeObjectURL(url);
  } catch (error) {
    console.error('下载失败:', error);
  }
};

封装通用下载函数

将重复逻辑封装为工具函数，便于复用并统一错误处理。

export const downloadFile = async (url, config = {}, defaultName = 'download') => {
  try {
    const response = await axios({ url, method: 'GET', responseType: 'blob', ...config });
    
    // 提取文件名
    const contentDisposition = response.headers['content-disposition'];
    let fileName = defaultName;
    if (contentDisposition) {
      const match = contentDisposition.match(/filename\*?=(?:UTF-8'')?([^;]+)/i);
      if (match) fileName = decodeURIComponent(match[1].replace(/['"]/, ''));
    }

    const blob = new Blob([response.data], {
      type: response.headers['content-type'] || 'application/octet-stream'
    });
    const downloadUrl = window.URL.createObjectURL(blob);
    const link = document.createElement('a');
    link.href = downloadUrl;
    link.download = fileName;
    link.style.display = 'none';
    document.body.appendChild(link);
    link.click();

    setTimeout(() => {
      document.body.removeChild(link);
      window.URL.revokeObjectURL(downloadUrl);
    }, 100);

    return { success: true, fileName };
  } catch (error) {
    console.error('下载失败:', error);
    throw error;
  }
};

常见问题与优化方案

1. 拦截器统一处理

在请求拦截器中注入 Token，在响应拦截器中统一处理错误和文件流。

// 请求拦截器
axios.interceptors.request.use(config => {
  const token = localStorage.getItem('token');
  if (token) config.headers.Authorization = `Bearer ${token}`;
  return config;
});

// 响应拦截器
axios.interceptors.response.use(async response => {
  // 针对文件下载的特殊错误处理
  if (response.config.responseType === 'blob' && response.status !== 200) {
    const text = await response.data.text();
    try {
      const error = JSON.parse(text);
      return Promise.reject(error);
    } catch {
      return Promise.reject(new Error('下载失败'));
    }
  }
  return response;
}, error => Promise.reject(error));

2. 跨域配置

文件上传下载常涉及 CORS 问题。确保后端暴露 Content-Disposition 头，以便前端读取文件名。

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization
Access-Control-Expose-Headers: Content-Disposition

3. 防抖与并发控制

防止用户重复点击导致大量请求。可使用防抖库或在组件状态中锁定按钮。

import { debounce } from 'lodash';

const debouncedUpload = debounce(async (file, callback) => {
  try {
    const result = await uploadWithProgress(file, callback);
    return result;
  } catch (error) {
    console.error(error);
  }
}, 300, { leading: true, trailing: false });

4. 大文件内存优化

Axios 默认将整个响应加载到内存。对于超大文件，建议后端直接返回下载链接，或使用流式处理，避免浏览器崩溃。

总结

Axios 在处理文件交互时功能强大但细节繁多。通过合理配置 FormData、Blob 及 responseType，结合拦截器统一处理认证与错误，可以构建稳定可靠的文件上传下载模块。实际项目中，还需根据文件大小和业务场景选择合适的策略，如异步任务轮询导出或本地压缩上传，以平衡性能与体验。