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

二、问题分析与优化方案

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(/['"]/,"");
    }
    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 行在内存中
}

正确设置响应头：

// 推荐使用 RFC 5987 标准
response.setHeader("Content-Disposition","attachment; filename*=UTF-8''"+URLEncoder.encode(filename,"UTF-8"));

3.2 前端最佳实践

浏览器兼容方案：

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

完善的错误处理：

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

正确处理 Blob 响应：

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

四、扩展思考

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

结语

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