spring mvc 文件下载核心是设置 content-disposition 和 content-type 响应头，并用 responseentity 封装字节数组返回；中文文件名需按浏览器兼容 utf-8 或 iso-8859-1 编码。

Spring MVC 处理文件下载，核心不是“怎么读文件”，而是“怎么告诉浏览器：这是要下载的文件，不是要打开的网页”。关键靠两个响应头控制行为，配合合适的返回方式避免常见坑。

必须设置的两个响应头

浏览器是否弹出保存对话框，主要取决于：

• Content-Disposition：值设为 attachment; filename="xxx"。其中 attachment 表示强制下载；filename 是用户看到的默认文件名（注意中文编码问题）
• Content-Type：推荐统一设为 application/octet-stream，表示通用二进制流。若明确类型（如 PDF、PNG），也可用 application/pdf 或 image/png，但非必需

推荐用 ResponseEntity 封装返回

这是最简洁、安全的方式，把字节数组、响应头、状态码一次封装，避免手动操作输出流出错：

Alibabacloud Sdk Client Initialization For Java

在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。

下载

• 读取文件为字节数组（可用 FileUtils.readFileToByteArray() 或 StreamUtils.copyToByteArray()）
• 构造 HttpHeaders，调用 setContentDispositionFormData("attachment", fileName)（Spring 5.1+ 推荐）
• 设置 contentType 为 MediaType.APPLICATION_OCTET_STREAM
• 返回 new ResponseEntity<byte>(bytes, headers, HttpStatus.OK)</byte>

中文文件名要特别处理

不同浏览器对 UTF-8 文件名支持不一，尤其 IE/Edge 需兼容 ISO-8859-1 编码：

• 传统做法：先将文件名按 UTF-8 编码成字节，再用 ISO-8859-1 解码成字符串，即 new String(fileName.getBytes("UTF-8"), "ISO-8859-1")
• 现代做法（Spring 5.0+）：用 ContentDisposition.attachment().filename("中文名.pdf", StandardCharsets.UTF_8).build()，支持标准 filename* 字段
• 若需兼顾老旧浏览器，可结合 User-Agent 判断后动态选择编码策略

别用 void + HttpServletResponse 写输出流

虽然可行，但容易引发问题：

• 忘记调用 flush() 或 close()，导致文件不完整
• 未设置 Content-Length，部分客户端无法显示下载进度
• 异常发生时响应流可能已提交，导致错误页无法正常渲染

Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南