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)
中文文件名要特别处理
不同浏览器对 UTF-8 文件名支持不一，尤其 IE/Edge 需兼容 ISO-8859-1 编码：
立即学习“Java免费学习笔记（深入）”；
- 传统做法：先将文件名按 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，部分客户端无法显示下载进度 - 异常发生时响应流可能已提交，导致错误页无法正常渲染
