Spring Boot 文件下载全场景实战：从静态资源到断点续传与MinIO

做后端这几年文件上传下载这种功能看起来不起眼但真正放到生产环境跑一段时间你会发现坑全藏在细节里。springboot 文件下载我写过不下十种版本从静态资源直连到对象存储签名 URL每个阶段的理解都不一样。今天这篇文章想把基于 Spring Boot 做文件下载的完整思路梳理一遍包括最基础的静态资源映射、动态流式下载、断点续传、大文件性能优化以及和 MinIO 这类对象存储的整合方式。适合正在用 springboot 开发后台管理系统或者准备搭一个独立文件服务的同学参考读完基本能覆盖日常开发中 90% 的文件下载场景。1. 文件下载为什么会单独拿出来说1.1 常见的下载需求场景很多人觉得文件下载无非就是给前端返回一个地址但真实的业务场景远没有这么简单。按照我接触过的项目需求大概能分成这么几类第一种是普通的附件下载比如导出 Excel、下载合同 PDF、拉取用户上传的头像文件不大几 KB 到几十 MB第二种是大文件下载比如视频课程、离线安装包、测试数据包动不动就是几个 GB这种必须考虑内存占用和用户体验第三种是私有文件下载比如内部资料、付费内容不能直接放到静态目录里让任何人访问需要做权限校验和时效控制第四种是对象存储场景文件放在 MinIO、OSS 或者云存储上Spring Boot 只负责生成下载地址或者做流量转发。这几种场景的技术选型完全不同如果把第一种的思路直接套到第二种生产上很快就会出现内存溢出或者连接超时。我见过一个项目用最原始的Files.readAllBytes()去下载一个 2GB 的安装包服务端直接内存被打满接口超时最后不得不重启机器。这类问题本质上就是没有理解文件下载的本质文件下载不是一个“读取文件并返回”的操作而是一个“把数据流从磁盘或者云存储正确传输到客户端”的过程里面的每一步——输入流的读取方式、响应头的设置、缓冲区的选择——都会影响最终结果。1.2 我为什么推荐从 IO 流理解文件下载我在和很多初级开发者交流时发现大家最容易卡住的地方不是写不出下载接口而是出了问题不知道从哪里排查。比如下载下来的文件总是比原文件少几个字节或者中文文件名在浏览器里变成乱码又或者下载大文件时客户端进度条卡住不动。这些问题如果只停留在“接一个接口、调一个方法”的层面根本找不到原因。所以我一直建议把文件下载当成一个完整的 IO 流程来理解服务端要明确知道文件在哪、文件有多大、用什么方式分段写出去客户端要明确知道这个响应是什么类型、是附件还是内联展示、长度是多少。Spring Boot 只是帮你把整个流程里的“路由”和“模板”部分简化了核心的 IO 处理仍然需要你自己掌握。理解了这一点之后你再回头看 Spring Boot 提供的各种下载方法就会清晰很多它们本质上都是对“输入流到输出流”这一过程的封装区别只在于封装的程度和适用的场景。下面我按实战中从简单到复杂的顺序把几种主流的下载方案逐个拆开讲。2. 静态资源下载最简单的直通方案2.1 静态资源映射约定如果你的文件本来就是想给所有人公开访问的比如软件安装包、公开的模板文件、产品介绍 PPT那最简单的方式就是把文件放到 Spring Boot 的静态资源目录里。默认约定是classpath:/static你放进去之后浏览器直接访问http://ip:8080/文件名就能下载。也可以同时配置多个静态资源位置比如把外部的磁盘目录也挂进来在application.yml里这样写spring: web: resources: static-locations: classpath:/static/,file:/data/public/这里的file:/data/public/表示把服务器上的/data/public目录也映射为静态资源路径之后访问http://ip:8080/report/2024/summary.pdf实际上读取的就是文件系统里的/data/public/report/2024/summary.pdf。这个方案最大的优势是零代码Spring Boot 自带的ResourceHttpRequestHandler会处理所有细节包括媒体类型判断、缓存控制等。配置完之后不需要重启的修改也可以直接生效非常适合快速交付一些内部小工具。不过要提醒一句静态资源映射的下载行为取决于请求路径的设计。Spring Boot 对已知资源类型会自动返回对应的Content-Type比如.pdf会返回application/pdf浏览器拿到这个类型之后通常会直接内联打开而不是下载。如果你希望所有静态资源都强制触发下载需要写一个WebMvcConfigurer自定义ResourceHttpRequestHandler的Content-Disposition响应头或者干脆不要把这类文件放在静态目录里而是走后面说的 Controller 方案。2.2 静态资源的两个实际坑第一个坑是路径穿越。如果配置了外部磁盘目录映射并且路径拼接没有做约束攻击者可以用../尝试读取你服务器上的其他文件。虽然 Spring Boot 默认带了一些防护但我还是建议不要直接开放整个根目录尽量映射到专用的子目录并且通过拦截器限制允许访问的文件后缀。第二个坑是缓存问题。默认情况下Spring Boot 对静态资源会返回带有效期和 ETag 的缓存头这本来是个好事但如果你更新了同名文件客户端可能还在使用旧的缓存版本。这时候可以在配置里调整缓存策略spring: web: resources: cache: period: 0这样每次请求都会重新读取文件代价是性能下降所以生产环境建议只在文件名带版本号或者更新不频繁的场景下使用静态映射否则还是用我下面写的 Controller 方案更灵活。3. 动态文件下载最常用的三种写法3.1 方式一ResponseEntity FileSystemResource当文件路径存储在数据库里或者需要根据登录用户动态指定下载文件时就不能靠静态映射了需要自己写 Controller。我最常用的是ResponseEntityResource这种方式因为写法干净返回值本身就是完整的 HTTP 响应对象方便测试和调试。核心代码如下GetMapping(/download/{fileName}) public ResponseEntityResource download(PathVariable String fileName) throws IOException { Path basePath Path.of(/data/private).toAbsolutePath().normalize(); Path fullPath basePath.resolve(fileName).normalize(); // 防止路径穿越 if (!fullPath.startsWith(basePath)) { return ResponseEntity.badRequest().build(); } Resource resource new FileSystemResource(fullPath); if (!resource.exists()) { return ResponseEntity.notFound().build(); } return ResponseEntity.ok() .header(HttpHeaders.CONTENT_DISPOSITION, attachment; filename\ fileName \) .contentType(MediaType.APPLICATION_OCTET_STREAM) .contentLength(resource.contentLength()) .body(resource); }这段代码有几个地方值得留意。第一Path.of(...).normalize()必须做否则fileName传../application.yml就能读到配置文件了这是文件下载接口最常见的安全漏洞。第二ResponseEntity里的contentLength一定要写不要省略。客户端下载文件时依靠这个响应头显示进度条如果没有它有些下载工具会直接判定文件大小未知导致进度条不动或者无法合并分段下载。第三APPLICATION_OCTET_STREAM是二进制流类型浏览器收到之后默认会走下载而不是打开这个类型对绝大多数场景都适用它相当于告诉浏览器“别猜这个文件是什么了直接保存”。写到这里有人会问为什么不用return new File(...)或者直接返回File对象Spring MVC 确实支持这么做比如方法返回File类型框架会自动写响应。但我实测下来这种方式在异常处理和自定义响应头方面不够灵活比如文件不存在时默认还会返回 200前端拿到的是一段空内容排查起来很被动。所以统一用ResponseEntityResource作为标准写法状态码和响应头都显式控制行为完全可预期。3.2 方式二HttpServletResponse 直接写流ResponseEntity适合绝大多数文件下载场景但当你要对输出过程做更精细的控制时比如写入日志、统计下载流量、或者把多个业务动作合并到一次响应里直接用HttpServletResponse更顺手。下面是我常用的模板GetMapping(/download/stream) public void streamDownload(RequestParam String fileName, HttpServletResponse response) throws IOException { File file new File(/data/private, fileName); if (!file.exists()) { response.setStatus(HttpServletResponse.SC_NOT_FOUND); return; } response.setContentType(application/octet-stream); response.setHeader(Content-Disposition, attachment; filename URLEncoder.encode(fileName, StandardCharsets.UTF_8)); response.setContentLengthLong(file.length()); try (InputStream is new FileInputStream(file); OutputStream os response.getOutputStream()) { byte[] buffer new byte[4096]; int bytesRead; while ((bytesRead is.read(buffer)) ! -1) { os.write(buffer, 0, bytesRead); } os.flush(); } }这里有个细节我希望大家能注意到通过response.getOutputStream()拿到的输出流写完之后在try-with-resources里会被自动关闭但有些版本的 Servlet 容器在关闭输出流之后还会尝试 commit response如果你在代码里又去设置响应头就会抛出IllegalStateException。所以我的习惯是先把所有响应头都设置好再打开输出流之后就不动响应对象了。buffer的大小也值得讲一下。缓冲区太小会导致任务线程频繁执行 IO 读写CPU 空转严重缓冲区太大则占用内存多用户同时下载时容易把堆撑爆。在我这边压测过的项目里4KB 到 16KB 是最稳定的区间超过 16KB 之后性能提升非常有限反而增加了内存压力。你可以把缓冲区大小做成配置项方便上线后根据实际并发调整。3.3 方式三InputStreamResource 与流式返回如果要下载的文件不是磁盘上的真实文件而是动态生成的内容比如把数据库查询结果生成 CSV、把报表模板渲染成 Excel那FileSystemResource就用不了了。这时候推荐InputStreamResource配合ResponseEntity返回GetMapping(/export) public ResponseEntityResource exportCsv() { StringBuilder sb new StringBuilder(); sb.append(姓名,部门,工号\n); sb.append(张三,研发部,1001\n); byte[] data sb.toString().getBytes(StandardCharsets.UTF_8); ByteArrayInputStream in new ByteArrayInputStream(data); return ResponseEntity.ok() .header(HttpHeaders.CONTENT_DISPOSITION, attachment; filenameemployees.csv) .contentType(MediaType.parseMediaType(text/csv)) .body(new InputStreamResource(in)); }需要留意的是InputStreamResource虽然叫 Resource但它的contentLength()方法通常不知道流里面有多少数据因为需要预先读取整个流才能算出长度。如果下载过程中进度条没有显示总大小大概率就是这个问题。解决办法有两个如果你知道数据大小手动设置contentLength如果你的流本身是从文件来的优先使用FileSystemResource或者下面的流式响应方案让 Tomcat 自己用零拷贝方式传输。对于异步响应式下载Spring Boot 还提供了StreamingResponseBody它允许你在后台线程中写输出流不占用请求线程对需要长时间执行的下载任务很有帮助GetMapping(/download/async) public StreamingResponseBody downloadAsync() { return outputStream - { try (InputStream is new FileInputStream(/data/private/big.iso)) { byte[] buffer new byte[8192]; int len; while ((len is.read(buffer)) ! -1) { outputStream.write(buffer, 0, len); } } }; }这种方式的优点是不会长时间占用 Tomcat 的线程池适合那种“启动任务然后慢慢生成文件”的场景。但它有个隐藏风险连接可能在流还没写完的时候被客户端断开此时你继续往 outputStream 里写数据会抛出异常。所以使用流式响应时要捕获客户端的断开异常做合理的日志记录避免产生大量无意义的堆栈信息。4. 中文文件名与下载头最容易翻车的细节4.1 不同浏览器的文件名编码策略如果说 IO 流处理是文件下载的骨架那响应头的内容就是它的神经。很多项目上线后运营反馈“下载的合同附件在 Chrome 里变成乱码”“iPhone 上下载的 PDF 文件名变成一串 % 号”其实就是Content-Disposition这个响应头没有正确处理中文导致的。早期规范里Content-Disposition的文件名参数只支持 ASCII 字符所以中文需要做 URL 编码写法通常是response.setHeader(Content-Disposition, attachment; filename URLEncoder.encode(项目合同.pdf, StandardCharsets.UTF_8));这样设置之后Chrome 和 Firefox 都能正确识别并解码但 IE 和部分老内核浏览器不认这种格式它们需要你额外提供一个filename*参数格式是filename*UTF-8%E9%A1%B9%E7%9B%AE...。老实说大部分现代项目已经不需要再兼容 IE 了但如果你的用户群体里有企业客户还是建议把兼容代码写上。一个比较通用的写法private String buildContentDisposition(String fileName) throws UnsupportedEncodingException { String encoded URLEncoder.encode(fileName, StandardCharsets.UTF_8).replaceAll(\\, %20); return attachment; filename\ encoded \; filename*UTF-8 encoded; }这里有个小坑我踩过URLEncoder.encode()会把空格编码成加号但在 HTTP 头的文件名参数里加号是不会被解析成空格的所以必须把手动替换成%20。如果你不替换中文文件名里带空格的场景比如“第一季度 收入报表.pdf”下载下来就变成了QuarterlyIncomeReport.pdf非常难看。4.2 Content-Type 与缓存控制Content-Type的选型也需要细心。很多人习惯全部设置成application/octet-stream这确实最安全但会牺牲掉部分用户体验比如下载一个.pdf明明浏览器插件可以内联预览结果被强制下载了。反过来如果不设置Content-Type又会导致一些浏览器对未知文件直接当作纯文本打开页面上一堆乱码。我的建议是通用的二进制文件统一用application/octet-stream有明确展示需求的文件比如图片、PDF、视频使用MediaType里对应的类型同时搭配inline或attachment的 disposition 来控制展示还是下载。还有一点容易忽略的是缓存头。文件下载接口默认每次都会从磁盘读取这对大文件或者高并发场景压力很大。如果文件本身不会变化可以在响应里加上缓存信息response.setHeader(Cache-Control, public, max-age3600);但要注意一旦带了缓存头用户修改了文件但文件名没变时客户端拿到的还是旧内容。所以实践中更常见的做法是对静态文件加缓存、对动态权限文件禁用缓存。禁用缓存可以这样设置response.setHeader(Cache-Control, no-store); response.setHeader(Pragma, no-cache);5. 大文件下载与性能优化5.1 零拷贝与底层优化大文件下载比如 1GB 以上的视频、安装包如果还用InputStream逐字节复制性能是很大的浪费。因为数据要从磁盘读到内核空间再复制到用户空间然后再写回内核空间通过 Socket 发出去中间多了一次内存拷贝。Linux 系统有一种优化叫零拷贝zero-copy通过sendfile系统调用让内核直接把文件数据从磁盘发送到网络设备完全绕过用户空间。Java 里的FileChannel.transferTo()底层就利用了这种机制。在 Spring Boot 中如果你的下载接口直接返回FileSystemResource当 Tomcat 配置了合适的连接器时它可以自动走零拷贝路径。但如果你手动用InputStream去读文件再写输出流就会强制走用户空间大文件场景下性能差距会非常明显。所以我的经验是只要文件在本地磁盘上就不要自己手动复制流直接交给 Spring 的Resource和响应机制让框架和 Servlet 容器帮你做优化。还有一个相关的点文件下载接口和普通接口尽量隔离尤其是大文件服务最好使用单独的连接器线程池配置并且给下载请求设置合理的读写超时。默认情况下 Tomcat 的连接超时可能只有几十秒下载一个大文件时连接被判定超时客户端就会频繁中断重连。我一般会把下载专用的 Servlet 服务超时时间调大或者用StreamingResponseBody配合异步线程池来处理。5.2 限速与并发控制大文件下载的另一个问题是带宽占用。公司内部服务如果不对下载做任何限制几个人同时拉一个 5GB 的安装包整条出口带宽可能就被塞满了其他业务的请求响应速度就会明显下降。我们曾经在文件服务上做过限速核心思路是控速写GetMapping(/download) public void throttledDownload(HttpServletResponse response) throws IOException { try (InputStream is new FileInputStream(/data/files/big.iso); OutputStream os response.getOutputStream()) { byte[] buffer new byte[8192]; int len; long startTime System.currentTimeMillis(); long bytesWritten 0; long maxBytesPerSecond 1024 * 1024 * 2; // 每秒2MB while ((len is.read(buffer)) ! -1) { os.write(buffer, 0, len); bytesWritten len; long elapsed System.currentTimeMillis() - startTime; long expectedElapsed bytesWritten * 1000 / maxBytesPerSecond; if (expectedElapsed elapsed) { Thread.sleep(expectedElapsed - elapsed); } } } catch (InterruptedException e) { Thread.currentThread().interrupt(); } }这样实现比较粗糙但对于内部系统够用。更优雅的方式是使用 Guava 的RateLimiter或者干脆用 Nginx 的限速模块在反向代理层做流量控制让 Spring Boot 不用关心带宽问题。如果你只是做一个中小型内部系统我建议优先用 Nginx 层限速毕竟应用层做限速会牺牲吞吐量而且调试起来也不够直观。5.3 Java 21 虚拟线程下的下载顺手提一个比较新的内容最近很多项目开始升级 JDK 21Spring Boot 3.2 及以上版本支持虚拟线程。虚拟线程对文件下载这类 IO 密集型任务有天然优势因为下载逻辑的大部分时间都阻塞在 IO 上传统线路程池一个线程往往只能处理一个下载请求而虚拟线程可以创建成千上万个极大提升并发能力。开启方式非常简单在application.yml里spring: threads: virtual: enabled: true开启后Spring MVC 的请求处理会自动切换到虚拟线程实测在我的机器上并发下载的吞吐量提升非常明显。不过要注意虚拟线程不适合跑 CPU 密集型任务比如下载时顺带做文件加密、压缩这种耗 CPU 的操作建议把这些逻辑放到线程池里隔离避免影响下载主流程。还有一点虚拟线程下如果代码里有synchronized锁或者Thread.sleep这种阻塞操作要特别小心JDK 的虚拟线程调度器会在阻塞点释放载体线程但像 synchronized 这种锁JDK 21 之后也会做锁的重新调度不过为了保险起见下载场景里尽量不要写持锁操作。6. 断点续传与 Range 请求6.1 Range 请求的原理现在支持断点续传的下载工具本质上都在发 HTTP Range 请求。客户端拿不到完整文件时会携带一个Range: bytes0-1023的请求头表示“我只想要文件的这个片段”服务器正确响应之后返回206 Partial Content状态码并把Content-Range响应头写清楚。这也是视频播放拖进度条、下载工具多线程分段下载的基础。Spring Boot 的静态资源处理器本身支持 Range 请求所以走静态映射的文件自动就能断点续传。但自定义的 Controller 下载接口不会自动支持需要自己写。我一次做视频点播项目时前端拖进度条频繁失败排查之后发现就是后端没有处理Range头整个请求被当成从头读取的完整下载每次拖拽都要重新拉整个视频自然卡得不行。6.2 一个简单的 206 实现思路手动支持 Range 请求的核心逻辑如下先读取请求头Range解析出开始和结束位置然后设置响应状态为 206并写好Accept-Ranges、Content-Range、Content-Length头最后用RandomAccessFile.seek()定位到起点开始输出。核心代码GetMapping(/play/{fileName}) public void play(RequestHeader(value Range, required false) String range, PathVariable String fileName, HttpServletResponse response) throws IOException { Path file Path.of(/data/video, fileName); long fileSize Files.size(file); long start 0; long end fileSize - 1; if (range ! null range.startsWith(bytes)) { String[] parts range.substring(6).split(-); start Long.parseLong(parts[0]); if (parts.length 1 !parts[1].isEmpty()) { end Math.min(Long.parseLong(parts[1]), end); } } if (start fileSize || start end) { response.setStatus(HttpServletResponse.SC_REQUESTED_RANGE_NOT_SATISFIABLE); response.setHeader(Content-Range, bytes */ fileSize); return; } response.setStatus(HttpServletResponse.SC_PARTIAL_CONTENT); response.setHeader(Accept-Ranges, bytes); response.setHeader(Content-Range, String.format(bytes %d-%d/%d, start, end, fileSize)); response.setContentLengthLong(end - start 1); response.setContentType(video/mp4); try (RandomAccessFile raf new RandomAccessFile(file.toFile(), r); OutputStream os response.getOutputStream()) { raf.seek(start); byte[] buffer new byte[4096]; long remaining end - start 1; int len; while (remaining 0 (len raf.read(buffer, 0, (int) Math.min(buffer.length, remaining))) ! -1) { os.write(buffer, 0, len); remaining - len; } } }这个实现虽然简单但能解决视频拖动、下载工具断点续传的绝大多数问题。更完整的处理还应该考虑If-Range、多 Range 段、ETag 等细节但对于普通业务系统一个单 Range 的 206 响应已经能带来很大的体验提升。7. 整合 MinIO把文件服务迁移到对象存储7.1 MinIO 与 Spring Boot 整合步骤很多项目的文件最终没有放在服务器本地而是放到了 MinIO 这类兼容 S3 协议的对象存储里。MinIO 最典型的部署方式是 Docker 单机或集群服务端负责管理分片、元数据和生命周期应用侧只是调用 SDK。把 MinIO 集成进 Spring Boot 用的依赖是io.minio:minio最新稳定版在 Maven 上可以直接搜到。初始化客户端时可以这样写Configuration public class MinioConfig { Value(${minio.endpoint}) private String endpoint; Value(${minio.access-key}) private String accessKey; Value(${minio.secret-key}) private String secretKey; Bean public MinioClient minioClient() { return MinioClient.builder() .endpoint(endpoint) .credentials(accessKey, secretKey) .build(); } }下载文件一般有两种方式。第一种是生成预签名 URL客户端拿到 URL 后直接向 MinIO 发起请求应用服务器不经过文件内容压力最小GetMapping(/minio/url) public String presignedUrl(RequestParam String objectName) throws Exception { return minioClient.getPresignedObjectUrl( GetPresignedObjectUrlArgs.builder() .method(Method.GET) .bucket(bucketName) .object(objectName) .expiry(600) .build() ); }第二种是服务端拉取再转给客户端这种方式适合需要做权限校验、水印、或者统一计数的场景GetMapping(/minio/download) public void downloadFromMinio(RequestParam String objectName, HttpServletResponse response) throws Exception { GetObjectArgs args GetObjectArgs.builder() .bucket(bucketName) .object(objectName) .build(); try (InputStream is minioClient.getObject(args); OutputStream os response.getOutputStream()) { response.setContentType(application/octet-stream); response.setHeader(Content-Disposition, attachment; filename URLEncoder.encode(objectName, StandardCharsets.UTF_8)); byte[] buffer new byte[8192]; int len; while ((len is.read(buffer)) ! -1) { os.write(buffer, 0, len); } } }两种方式我都在生产环境用过如果是私有文件或者对访问有时效控制需求预签名 URL 更合适因为可以不暴露 Bucket 的读写权限如果文件需要经过应用层做审计、权限控制、或者给用户显示下载次数就走服务端转发。7.2 预签名 URL 与流式转发怎么选这里说说选型时的判断依据。预签名 URL 的优点很明显下载不占应用服务器带宽和连接MinIO 自己处理高并发缺点是 URL 会过期默认我一般设置为 10 分钟超时后需要重新生成而且一旦 URL 泄露在过期之前谁都可以下载所以敏感文件不建议用长时效的预签名地址。服务端流式转发的优点是可以叠加业务逻辑比如记录日志、检查积分、控制并发缺点是所有文件流量都要经过 Spring Boot 应用应用的出口带宽、线程池、Socket 连接数很快就会成为瓶颈。如果项目文件平均不到 50MB用服务端转发没什么问题如果是视频平台或者镜像站我只推荐预签名 URL或者用 Nginx 的反向代理作为中转层不要让 Java 应用直接扛大流量。8. 安全校验与权限控制8.1 校验登录态与路径穿越文件下载接口是安全攻击的重灾区主要原因是它让外部请求直接映射到了服务器文件路径。最基本的两条防线是登录态校验和路径穿越防护。登录态校验通常用 Spring Security 或者自定义拦截器完成确保只有通过认证的用户才能访问下载接口。路径穿越防护则需要特别小心我上面代码里已经演示了用Paths.normalize()和startsWith()双重验证实际项目中还需要限制文件后缀比如只允许.pdf,.docx,.png其他一律拒绝。不要以为接口路径上带着随机数就安全了很多系统生成的文件名是纯数字 ID 或者简单的日期拼接攻击者完全可以遍历。更稳妥的做法是数据库中的文件记录使用随机生成的存储名对外展示的下载文件名单独存储用户传给后端的只是一个 UUID 关联 ID服务端根据 ID 去数据库查真实路径。这样即使接口暴露了也无法直接猜出其他文件的路径。8.2 防刷与限流文件下载接口一般比普通接口更容易被恶意刷取尤其是大文件下载每次都会消耗大量带宽和 IO。实践中我一般叠加三层防护第一层是登录状态校验未登录用户直接拒绝第二层是下载频率控制用 Redis 记录每个用户每小时的下载次数超过阈值就返回 429第三层是根据文件大小动态计算带宽占用如果同一个用户长时间占用高带宽就自动降级或者断开连接。还可以考虑给下载接口加上签名参数比如给前端发放一个带时效的 token只有拿到 token 之后才能下载指定文件防止接口被直接外链。这种方案在小程序、开放平台场景下很常见。我见过一个教育类项目课件的下载地址直接硬编码在前端被别站盗链之后损失很大后来就是改成签名 URL 解决的。9. 常见问题与排查技巧实录9.1 问题速查表我把实际开发中遇到的高频问题整理成一张速查表方便大家对照排查。现象可能原因解决方案下载文件名中文乱码Content-Disposition 未做编码处理使用 URLEncoder 编码并且配置 filename* 参数下载文件大小不对或文件损坏响应头 Content-Length 与实际写入长度不一致先设置 Content-LengthLong 再写流或让框架自动计算浏览器直接打开而不是下载Content-Disposition 没有设置为 attachment检查响应头确保 disposition 类型正确大文件下载时内存溢出用了 Files.readAllBytes 或 byte[] 全量读取改为流式传输、Resource 或 StreamingResponseBody下载到一半断掉连接超时设置过短调大服务器读写超时或使用异步流式响应前端拿到 blob 后保存格式不对ResponseType 设置错误或 MIME 类型不匹配检查前端请求 responseType 和后端 Content-Type静态资源更新后访问旧文件浏览器缓存设置 Cache-Control 或者文件名带版本号动态生成的 CSV 下载后乱码字节流没有 BOM 头在写 CSV 之前写入 UTF-8 BOM 字节下载接口高并发下响应慢未使用零拷贝或线程阻塞改用 Resource、虚拟线程或前置 CDN/Nginx9.2 我实际踩过的几个坑第一个坑是 IDEA 里开发时文件下载正常部署到 Docker 就 404。排查之后发现是因为 Docker 容器的/tmp目录被清理了而我用File.createTempFile()生成的临时文件就放在/tmp下面。这个问题在长期运行的容器里非常隐蔽因为不是启动就挂而是跑几天之后突然报错。后来我的做法是给应用配置一个独立的临时目录通过-Djava.io.tmpdir/data/tmp启动参数指定并且用 volume 持久化挂载这样既不会丢数据也不会被系统清理。第二个坑是前端用 fetch 下载文件时如果后端返回的是 302 重定向fetch 默认会跟随并且拿不到真正的下载地址导致流式下载失败。这个问题我在接预签名 URL 时遇到过。解决方案是让前端先请求一个接口获取预签名地址然后使用window.location.href直接跳转下载或者使用axios的responseType: blob配合拦截器处理不要依赖 fetch 的 follow 行为。第三个坑是日志打印问题。下载接口如果打印日志太频繁比如每个 buffer 都打一行一个 2GB 文件就能打满磁盘。我自己的规范是下载接口只打印请求开始、响应状态、总字节数不打印每个数据块这样出现问题也能定位同时不会刷爆日志。还有一点想特别提一下很多人开发时用 Postman 测下载接口看到响应体是二进制就以为成功了但 Postman 对二进制内容的显示不一定准确推荐测试时用curl -O下载到本地再对比文件大小或者写一个自动校验的脚本。我自己习惯用如下命令快速验证curl -O -L http://localhost:8080/download/xxx.pdf md5sum xxx.pdf拿到文件之后和源文件比对 MD5一致才算接口真正通过。这个习惯帮我避免过很多次“接口返回 200 但文件其实损坏”的问题。写在最后的实操心得文件下载这个功能单独看很简单但和 Spring Boot 的静态资源、IO 流、响应协议、安全控制一结合就藏了不少门道。我个人在实际操作中的体会是先分清楚你的文件是公开静态文件、业务私有文件还是大文件、对象存储文件再决定用哪种下载方式不要一上来就写 Controller。如果只是公开附件静态资源配置解决如果是业务文件用ResponseEntityResource配合路径校验如果文件可能超过 500MB直接考虑 Range 请求和零拷贝如果文件压根不在服务器上尽早用预签名 URL。另外还有一个习惯值得推荐把文件下载相关的公共能力封装成一个工具或基类比如统一设置响应头、统一处理中英文文件名、统一记录下载日志、统一做限流判断。这样后续每个项目只需要关注自己的业务逻辑不用反复踩同样的坑。这个功能虽然不起眼但做得好的话对系统稳定性和用户体感的提升是实打实的。