前端文件下载实战：从原理到最佳实践

前端文件下载实战：从原理到最佳实践

引言

在现代 Web 应用开发中，文件下载是一个常见但容易出错的场景。本文将通过一个真实的订单导出功能案例，详细介绍前后端协作实现文件下载的完整方案，分析常见问题及解决方案，并提供经过生产验证的最佳实践。

一、需求背景与初始实现

1.1 业务需求

我们需要实现一个订单数据导出功能，允许用户将查询结果下载为 Excel 文件。具体要求包括：

• 支持按任务 ID 筛选订单
• 生成规范的 XLSX 格式文件
• 显示友好的下载状态
• 记录操作日志

1.2 初始后端实现

@ApiOperation(value = "下载订单列表", notes = "根据条件导出订单数据为 Excel 文件")
@PostMapping("/order-list/download")
public Result<?> downloadTaskOrderExcel(@RequestBody TaskDownLoadRequest taskDownLoadRequest, HttpServletRequest httpRequest) {
    try {
        // 获取用户 ID 并记录日志
        Integer userId = getUserId(taskDownLoadRequest.getTaskId());
        logDownloadStart(userId, taskDownLoadRequest.getTaskId());
        
        // 查询订单数据
        List<CustomerOrder> orders = queryOrders(taskDownLoadRequest.getTaskId());
        if (orders.isEmpty()) {
            return Result.error("没有找到符合条件的订单数据");
        }
        
        // 生成 Excel 文件
        ByteArrayResource resource = generateExcel(orders);
        
        // 构建响应数据
        Map<String, Object> data = buildResponseData(resource);
        return Result.ok(data);
    } catch (Exception e) {
        log.error("下载订单列表失败", e);
        return Result.error(500, "下载订单数据失败");
    }
}

1.3 初始前端实现

const download = async (row) => {
    const loading = ElLoading.service({ text: "正在下载..." });
    try {
        const response = await commonApi.taskOrderListDownload(
            { taskId: row.id },
            { responseType: "blob" }
        );
        
        // 文件名解析逻辑
        let filename = "订单导出.xlsx";
        const disposition = response.headers['content-disposition'];
        if (disposition) {
            const match = disposition.match(/filename="?([^\"]+)"?/);
            if (match) filename = decodeURIComponent(match[1]);
        }
        
        // 创建下载链接
        const blob = new Blob([response.data], {
            type: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
        });
        const link = document.createElement("a");
        link.href = window.URL.createObjectURL(blob);
        link.download = filename;
        document.body.appendChild(link);
        link.click();
        document.body.removeChild(link);
        ElMessage.success("下载成功");
    } catch (e) {
        ElMessage.error("下载失败");
    } finally {
        loading.close();
    }
};

二、问题分析与优化方案

2.1 主要问题

1. 响应头访问问题：Cannot read properties of undefined (reading 'content-disposition')
2. 大文件内存问题：使用 ByteArrayResource 导致内存占用高
3. 文件名编码问题：中文文件名可能显示不正确
4. 错误处理不足：无法获取详细的错误信息

2.2 后端优化方案

2.2.1 流式响应改造

@PostMapping("/order-list/download")
public void downloadTaskOrderExcel(@RequestBody TaskDownLoadRequest taskDownLoadRequest, HttpServletResponse response) throws IOException {
    // 设置响应头
    String filename = "订单导出_" + LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyyMMdd_HHmmss")) + ".xlsx";
    response.setContentType("application/vnd.openxmlformats-officedocument.spreadsheetml.sheet");
    response.setHeader(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename*=UTF-8''" + URLEncoder.encode(filename, "UTF-8").replace("+", "%20"));
    
    // 流式生成 Excel
    try (OutputStream out = response.getOutputStream()) {
        orderService.generateExcelToStream(queryOrders(taskDownLoadRequest.getTaskId()), out);
    }
}

2.2.2 Excel 生成优化

public void generateExcelToStream(List<CustomerOrder> orders, OutputStream out) throws IOException {
    try (Workbook workbook = new SXSSFWorkbook(100)) {
        // 使用流式 Workbook
        Sheet sheet = workbook.createSheet("订单数据");
        
        // 创建标题行
        String[] headers = {"订单 ID", "客户姓名", "运单号", /* 其他字段 */};
        Row headerRow = sheet.createRow(0);
        for (int i = 0; i < headers.length; i++) {
            headerRow.createCell(i).setCellValue(headers[i]);
        }
        
        // 填充数据
        int rowNum = 1;
        for (CustomerOrder order : orders) {
            Row row = sheet.createRow(rowNum++);
            row.createCell(0).setCellValue(order.getId());
            // 其他字段...
        }
        workbook.write(out);
    }
}

2.3 前端优化方案

2.3.1 增强的文件名解析

function getFilenameFromHeaders(headers) {
    let filename = "订单导出_" + new Date().toISOString().slice(0, 10) + ".xlsx";
    const disposition = headers['content-disposition'] || headers['Content-Disposition'];
    if (!disposition) return filename;
    
    // 支持 RFC 5987 编码
    const utf8Match = disposition.match(/filename\*=UTF-8''([^;]+)/i);
    if (utf8Match && utf8Match[1]) {
        return decodeURIComponent(utf8Match[1]);
    }
    
    // 支持普通文件名
    const filenameMatch = disposition.match(/filename="?([^\"]+)"?/i);
    if (filenameMatch && filenameMatch[1]) {
        return filenameMatch[1].replace(/["']/g, '');
    }
    return filename;
}

2.3.2 完整的下载方法

const downloadFile = async (params, apiMethod, defaultFilename) => {
    try {
        const response = await apiMethod(params, {
            responseType: 'blob',
            headers: {
                'Accept': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
            }
        });
        
        // 解析文件名
        const filename = getFilenameFromHeaders(response.headers) || defaultFilename;
        
        // 创建下载链接
        const blob = new Blob([response.data], {
            type: response.headers['content-type'] || 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
        });
        
        if (window.navigator.msSaveOrOpenBlob) {
            // IE 专用方法
            window.navigator.msSaveOrOpenBlob(blob, filename);
        } else {
            const url = URL.createObjectURL(blob);
            const link = document.createElement('a');
            link.href = url;
            link.download = filename;
            link.style.display = 'none';
            document.body.appendChild(link);
            link.click();
            
            // 延迟清理
            setTimeout(() => {
                document.body.removeChild(link);
                URL.revokeObjectURL(url);
            }, 100);
        }
        return { success: true, filename };
    } catch (error) {
        // 尝试解析错误信息
        if (error.response?.data instanceof Blob) {
            try {
                const errorText = await error.response.data.text();
                const errorJson = JSON.parse(errorText);
                throw new Error(errorJson.message || '下载失败');
            } catch {
                throw new Error('文件下载失败');
            }
        }
        throw error;
    }
};

三、最佳实践总结

3.1 后端最佳实践

1. 使用流式响应：避免内存中保存完整文件
   • 使用 SXSSFWorkbook 处理大数据：

     try (Workbook workbook = new SXSSFWorkbook(100)) {
         // 只保留 100 行在内存中
     }
     

2. 正确设置响应头：
   • 推荐使用 RFC 5987 标准

     response.setHeader("Content-Disposition", "attachment; filename*=UTF-8''" + URLEncoder.encode(filename, "UTF-8"));
     

3.2 前端最佳实践

1. 浏览器兼容方案：

   // IE 浏览器兼容
   if (window.navigator.msSaveOrOpenBlob) {
       window.navigator.msSaveOrOpenBlob(blob, filename);
   } else {
       // 标准浏览器实现
   }
   

2. 完善的错误处理：

   try {
       // 下载逻辑
   } catch (error) {
       if (error.response?.status === 404) {
           showError("文件不存在");
       } else if (error.response?.status === 403) {
           showError("无下载权限");
       } else {
           showError("下载失败：" + (error.message || "未知错误"));
       }
   }
   

3. 正确处理 Blob 响应：

   const blob = new Blob([response.data], {
       type: response.headers['content-type'] || 'application/octet-stream'
   });
   

四、扩展思考

1. 断点续传：对于大文件可考虑 Range 请求支持
2. 进度显示：通过 axios 的 onUploadProgress 实现下载进度条
3. 安全控制：
   • 添加 CSRF Token 保护
   • 下载权限验证
4. 日志追踪：记录完整的下载日志用于审计

结语

文件下载功能看似简单，实则涉及前后端多个技术点的紧密配合。本文通过实际案例详细分析了常见问题及其解决方案，提供了经过生产验证的实现方案。希望这些经验能帮助开发者避免常见陷阱，构建更健壮的文件下载功能。