最近陆陆续续有不少人问我同一个问题：Spring Boot里的文件下载到底怎么写才不踩坑。有做毕设的在校生，有刚转后端的新人，也有已经上生产的兄弟在排查"下载下来的文件为什么乱码""文件一大就卡死"这类线上问题。聊一圈下来我发现一个规律：大多数人的下载接口都能跑，但离"能用"还差着好几道坎——文件超过几十兆就内存飙升、中文文件名乱得没法看、路径参数随手拼进URL带着安全隐患、接上MinIO之后应用服务器还被下载流量直接打穿。这篇文章把Spring Boot文件下载从最基础的写法讲到对象存储场景下的进阶方案，顺带把中文编码、断点续传、安全校验这些绕不开的细节全展开。不管是交毕设，还是做公司项目里的文件管理模块，或者马上要面试被问到"文件下载怎么设计"，照着这套思路走，基本能把这条路理顺。
1. 一个下载接口从"能跑"到"能用"，中间隔着四层设计
先看一段很多教程里都会出现的经典写法：
@GetMapping("/download/{filename}") public void download(@PathVariable String filename, HttpServletResponse response) throws IOException { File file = new File("/data/files/" + filename); byte[] data = Files.readAllBytes(file.toPath()); response.setContentType("application/octet-stream"); response.getOutputStream().write(data); response.getOutputStream().flush(); }我见过不少项目直接把这段代码带进生产环境，然后被运维找上门来。第一层问题是内存：Files.readAllBytes会把整个文件一次性读进JVM堆内存，一个50MB的文件就占50MB的byte数组，同时来20个下载请求，光文件数据就要占掉1GB堆，GC压力瞬间拉满，放在小规格容器里基本上就是OOM事故预告。所以下载接口设计的第一个问题就是：文件内容到底在不在内存里待着，能不能一行一行往响应流里搬。
第二层问题是Content-Type。所有文件都固定成application/octet-stream，浏览器拿到PDF、图片、Excel这些本来可以内置预览的文件，也只能乖乖弹下载框，体验大打折扣；反过来如果你为了能预览把类型放开，遇到HTML、SVG这类可以携带脚本的文件，又会引入存储型XSS风险。类型怎么定，后面第六节再展开。
第三层问题是文件名。上面这段代码压根没有设置Content-Disposition响应头，很多浏览器会拿URL最后一段当作下载文件名，路径里一旦有中文，要么乱码、要么文件名缺斤少两。我遇到过的"下载乱码"类工单，十个里有六个是Content-Disposition没做对。
第四层问题才是真正要命的：路径拼接。new File("/data/files/" + filename)这种写法，只要传一个../etc/passwd，就能顺着路径越过你预设的目录读系统文件。很多做毕设的同学意识不到这一点，但面试官只要看到简历里有文件下载功能，第一问大概率就是路径穿越怎么防。
我的建议是，拿到需求不要急着写代码，先把四个决策点定下来：
| 决策点 | 要问自己 | 备选方案 |
|---|---|---|
| 数据来源 | 文件在本地磁盘、数据库还是对象存储 | File / byte[] / MinIO、OSS SDK |
| 响应方式 | 文件多大、并发多少、要不要支持续传 | 字节数组、InputStreamResource、静态映射 |
| 类型策略 | 全部强制下载还是允许浏览器预览 | attachment / inline / 扩展名白名单 |
| 文件名编码 | 有没有中文、前端要不要读响应头 | RFC 5987 filename*、Access-Control-Expose-Headers |
把这四个点盘一遍再动手写代码，出来的接口通常不会返工。下面每个点都会单独展开讲，咱们先看最核心的选型。
2. Spring Boot三种主流下载姿势，先把选型想明白
2.1 小文件用ResponseEntity<byte[]>：省事但别贪心
如果文件是配置模板、几KB的小图标、内存里临时组装出来的报表，用字节数组直出是最清爽的：
@GetMapping("/download/config") public ResponseEntity<byte[]> downloadConfig() { byte[] data = "spring.application.name=demo".getBytes(StandardCharsets.UTF_8); return ResponseEntity.ok() .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename*=UTF-8''application.properties") .contentType(MediaType.APPLICATION_OCTET_STREAM) .body(data); }用ResponseEntity的好处是Spring MVC已经帮我们调好了响应头的写入顺序，Content-Length也会按字节数组长度自动生成，浏览器拿到的是完整HTTP响应。但这个方法的使用边界非常明确：文件必须真的小。一旦发现业务里文件体量可能超过几十兆，或者并发上来之后堆内存监控开始走高，就要立刻换方案。这个"小"的标准我一般卡在1MB以内，超过1MB我宁可用下面的流式方案。
2.2 标准解法：ResponseEntity + Resource 做流式响应
Spring从4.1开始给Resource提供了HttpMessageConverter，Controller可以直接返回Resource，Spring会自己读InputStream并把数据写到响应里，不需要你手动碰OutputStream。这应该算Spring Boot下载功能的标准解法：
@GetMapping("/download/{filename}") public ResponseEntity<Resource> download(@PathVariable String filename) throws IOException { Path basePath = Paths.get(UPLOAD_DIR).toAbsolutePath().normalize(); Path filePath = basePath.resolve(filename).normalize(); if (!filePath.startsWith(basePath)) { return ResponseEntity.badRequest().build(); } if (!Files.exists(filePath)) { return ResponseEntity.notFound().build(); } FileSystemResource resource = new FileSystemResource(filePath.toFile()); String encodedName = URLEncoder.encode(filePath.getFileName().toString(), StandardCharsets.UTF_8) .replace("+", "%20"); return ResponseEntity.ok() .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=\"download\"; filename*=UTF-8''" + encodedName) .contentType(MediaType.APPLICATION_OCTET_STREAM) .contentLength(resource.contentLength()) .body(resource); }这里有几个细节值得单独圈出来。
第一个是FileSystemResource和InputStreamResource的选择。FileSystemResource底层还是FileInputStream，但它能正确返回contentLength()，Spring的ResourceHttpMessageConverter写响应时会带上Content-Length，客户端解析时就明确了数据边界；InputStreamResource如果构造时没传长度，Spring会退化到分块传输，某些老旧代理、下载工具和断点续传工具会因此出问题。所以本地文件场景，优先FileSystemResource。
第二个是Content-Length头的意义。别小看这一行，它决定了浏览器下载进度条正不正常，也决定了客户端能不能判断下载是否被中断。很多"进度条不动""下载完文件打不开"的工单，最后查出来都是Content-Length没给对，要么缺失要么长度比实际文件大。
第三个是控制力。用ResponseEntity<Resource>时404、403、400这些错误可以随ResponseEntity一起返回；如果只写return resource，虽然也能跑，但错误状态码的处理就得依赖抛异常和@ControllerAdvice，控制力弱不少。
2.3 公开文件用静态资源映射：简单粗暴但控制力弱
如果文件本身就是公开资源，不想写Controller也不想碰下载逻辑，可以直接让Spring Boot的静态资源配置接管：
@Configuration public class WebMvcConfig implements WebMvcConfigurer { @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("/files/**") .addResourceLocations("file:/data/files/"); } }配置生效后，访问/files/report.pdf就能直接取到本地文件。这个方案的好处是零业务代码、自带Last-Modified缓存协商，浏览器第二次访问会带If-Modified-Since做304判断，省流量。但代价也很明显：没法方便地设置Content-Disposition，也就是没法强制浏览器"下载"而不是"打开"。对于PDF、图片这类需要新标签页预览的场景反而刚刚好。
顺带提一句热搜里那个"vue打包放进springboot中"。前端项目build之后把dist目录里的内容复制到src/main/resources/static下面，Spring Boot启动后自动就当成静态资源吐出去了，原理和上面的addResourceHandlers是一套。很多人做文件预览、文件下载都是从这步开始的，所以别觉得静态资源映射和你无关。
2.4 三种方案放到一起看
| 方案 | 适用场景 | 内存占用 | 是否支持断点续传 | 能控制下载文件名 |
|---|---|---|---|---|
| ResponseEntity<byte[]> | 小文件、动态生成内容 | 高（全量驻留） | 不支持 | 可以 |
| ResponseEntity | 本地文件、需要控制下载行为 | 低（流式） | 可以（配合Range） | 可以 |
| 静态资源映射 | 公开资源、浏览器预览 | 低 | 支持（容器自动处理） | 不支持attachment |
选型上没有绝对的对错，关键是知道自己为什么选。我在实际项目里的习惯是：上传产物这类"确定要下载"的文件用Resource方案，缩略图、操作手册这类"需要预览"的用静态映射，模板导出这类"内存里生成的"才用字节数组。下面紧接着就是下载流程里最容易被骂的一个环节——文件名。
3. 中文文件名这关过不去，下载功能就废了一半
3.1 Content-Disposition的历史包袱
响应头Content-Disposition是下载功能最关键的信息，它告诉浏览器这是要展示（inline）还是下载（attachment），并且通过filename参数指定下载文件的名字：
Content-Disposition: attachment; filename="report.xlsx"早期规范里filename只能写ASCII字符，中文没法放进去。后来RFC 5987定义了filename*参数，允许在头里放URL编码过的Unicode文件名，所以正确写法是把原始中文文件名做百分号编码之后放在filename*里，再给一个ASCII的普通filename当降级：
Content-Disposition: attachment; filename="download.xlsx"; filename*=UTF-8''%E6%9C%88%E6%8A%A5.xlsx注意filename*的格式是三段式：字符集、语言（可选）、百分号编码串，中间用两个单引号隔开。很多新手直接把中文文件名塞进filename="中文.xlsx"，老版本浏览器解析到非ASCII字符就直接截断或乱码，这就是"下载文件名乱码"最常见的根源。
3.2 后端编码工具方法
服务端写的编码方法一般长这样：
private String encodeFileName(String fileName) { return URLEncoder.encode(fileName, StandardCharsets.UTF_8) .replace("+", "%20"); }为什么要.replace("+", "%20")？因为URLEncoder会把空格编码成加号，而RFC 5987规定这里的空格应当编码成%20。要是不处理，文件名里带空格的，下载出来文件名会变成带加号的奇怪形状。虽然是小毛病，但一旦你的接口面向外部用户，这种细节很容易变成投诉素材。
然后组合响应头时，我建议固定写成：
response.setHeader(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=\"download\"; filename*=UTF-8''" + encodeFileName(originalName));ASCII的降级名不要拿中文去转，直接写一个固定的download或者download.data都行，保证老浏览器还能落一个能用的文件名。现代的Chrome、Edge、Firefox、Safari都优先读filename*，所以真正的下载名还是中文原名，只是给老环境一个兜底。
3.3 跨域场景下前端读不到文件名
如果你用了Vue这类前端框架，让前端自行从响应头解析文件名，会踩到另一个坑：浏览器跨域请求下，前端只能读取到CORS白名单里暴露的响应头，Content-Disposition默认不在里面。后端只要配了跨域，就需要手动把响应头暴露出去：
response.setHeader(HttpHeaders.ACCESS_CONTROL_EXPOSE_HEADERS, HttpHeaders.CONTENT_DISPOSITION);加了这一行，前端拿response.headers["content-disposition"]才不会总是undefined。我见过不少前端同事在这个问题上排查了一下午，最后发现不是代码问题，是响应头根本没露出来。跨域联调的时候，先把这个暴露头加上再往前端兜。
4. 大文件下载：从内存溢出到断点续传
4.1 为什么大文件会OOM
很多项目的下载接口最初都是字节数组写法。文件在10MB以内时毫无感觉，等业务一天天跑起来，文件变成了几百MB的压缩包、安装包，问题就集中爆发了。原因很简单：Files.readAllBytes、file.getBytes这类API会把文件一次性加载到堆内存，JVM里多来几个并发下载，内存瞬间暴涨。更麻烦的是，内存里的byte数组还不容易被GC快速回收，因为Controller方法栈、响应封装、容器缓冲区可能同时引用同一份数据。
处理大文件的核心思路只有一句：不要让文件内容在JVM内存中完整存在。要么流式读一段写一段，要么直接让客户端和文件存储之间建立连接。
4.2 流式拷贝的最优写法
不依赖任何工具库，原生写法如下：
@GetMapping("/download/stream/{filename}") public void streamDownload(@PathVariable String filename, HttpServletResponse response) throws IOException { Path basePath = Paths.get(UPLOAD_DIR).toAbsolutePath().normalize(); Path filePath = basePath.resolve(filename).normalize(); if (!filePath.startsWith(basePath) || !Files.exists(filePath)) { response.setStatus(HttpStatus.NOT_FOUND.value()); return; } String encodedName = URLEncoder.encode(filePath.getFileName().toString(), StandardCharsets.UTF_8) .replace("+", "%20"); response.setContentType(MediaType.APPLICATION_OCTET_STREAM_VALUE); response.setHeader(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename*=UTF-8''" + encodedName); response.setContentLengthLong(Files.size(filePath)); try (InputStream in = new BufferedInputStream(Files.newInputStream(filePath)); OutputStream out = response.getOutputStream()) { byte[] buffer = new byte[8192]; int len; while ((len = in.read(buffer)) != -1) { out.write(buffer, 0, len); } out.flush(); } }缓冲区定多少合适，其实是性能和内存的平衡。8192字节是Apache Commons IO默认的拷贝缓冲，也是我常年用的值。设成4KB更省内存但系统调用次数翻倍；调到64KB传输更快，但每个下载请求多占64KB堆，按100并发算就是6.4MB，通常也能接受。除非你做过压测并且对JVM内存有明确把握，否则不要盲目贪大，8KB起步最稳妥。
这个写法和前面return Resource的差别在于：手动控制输出流，可以在每个写入循环里插入额外逻辑，比如限速、记录下载进度。代价是要自己保证流的关闭，try-with-resources能确保异常路径也释放文件描述符。
另一个线程层面的坑，这里一并说了。默认Tomcat线程池是200，一个庞大的下载请求从开始写响应到完全结束，会一直占住一个工作线程。如果有人发一堆下载请求但又慢慢读数据，很容易把线程池占满，其他普通接口跟着遭殃。所以下载接口要么配合下载总量限额，要么把耗时下载放到独立线程池执行，要么在前端层面限制并发。大文件下载做得严谨的项目，基本都会在外面套一层网关限流。如果你已经升到Spring Boot 3.2+并且运行在Java 21上，可以开启spring.threads.virtual.enabled=true，这种阻塞式的流式下载会跑在虚拟线程上，Tomcat的工作线程不再被慢下载占死，前面说的线程池耗尽问题会缓解不少，升级成本很低，值得一试。
4.3 Range请求与断点续传
HTTP协议从1.1开始支持Range头，客户端可以只请求文件的一部分，服务器返回206 Partial Content。迅雷、浏览器自带下载器能"断点续传""多线程分段下载"，靠的就是这个机制。
Spring为Range请求提供了现成的支持。Controller可以返回ResourceRegion，ResourceRegionHttpMessageConverter会自动处理Range头、生成206状态和Content-Range响应头：
@GetMapping("/download/range/{filename}") public ResponseEntity<ResourceRegion> downloadRange( @PathVariable String filename, @RequestHeader(value = HttpHeaders.RANGE, required = false) String range) throws IOException { Path basePath = Paths.get(UPLOAD_DIR).toAbsolutePath().normalize(); Path filePath = basePath.resolve(filename).normalize(); if (!filePath.startsWith(basePath) || !Files.exists(filePath)) { return ResponseEntity.notFound().build(); } FileSystemResource resource = new FileSystemResource(filePath.toFile()); long contentLength = resource.contentLength(); List<HttpRange> ranges = HttpRange.parseRanges(range); if (ranges.isEmpty()) { return ResponseEntity.ok() .header(HttpHeaders.ACCEPT_RANGES, "bytes") .contentType(MediaType.APPLICATION_OCTET_STREAM) .body(new ResourceRegion(resource, 0, contentLength)); } HttpRange httpRange = ranges.get(0); long start = httpRange.getRangeStart(contentLength); long end = httpRange.getRangeEnd(contentLength); long rangeLength = Math.min(contentLength - 1, end) - start + 1; return ResponseEntity.status(HttpStatus.PARTIAL_CONTENT) .header(HttpHeaders.ACCEPT_RANGES, "bytes") .contentType(MediaType.APPLICATION_OCTET_STREAM) .body(new ResourceRegion(resource, start, rangeLength)); }这里有两个容易忽略的点。一是完整响应（没有Range头）时也要加上Accept-Ranges: bytes，告诉客户端这个接口支持分段下载；二是Content-Range别手动拼，ResourceRegionHttpMessageConverter会自动生成，手动写反而可能出现重复头，这是一个常见翻车细节。另外，HttpRange.parseRanges遇到格式非法的Range头会抛IllegalArgumentException，生产环境建议捕获一下，非法Range就回退成完整下载或者返回400，别让一个畸形请求把异常堆栈打到日志里。
支持Range之后，浏览器里点暂停、继续下载，都走同一套逻辑，用户体验直接上一个台阶。对下载工具类产品、安装包分发服务来说，Range支持基本是必选项。
4.4 限速下载：防止单用户吃满带宽
文件下载功能上线后最常见的运维投诉是"某个人在拉大文件，整个出口带宽被打满"。加一个最简单的匀速限速逻辑，按固定时间窗口控制写入量：
private static final int BYTES_PER_SECOND = 1024 * 1024; // 限速 1MB/s long bytesWritten = 0; long windowStart = System.currentTimeMillis(); while ((len = in.read(buffer)) != -1) { out.write(buffer, 0, len); bytesWritten += len; long elapsed = System.currentTimeMillis() - windowStart; long expectTime = bytesWritten * 1000L / BYTES_PER_SECOND; if (expectTime > elapsed) { try { Thread.sleep(expectTime - elapsed); } catch (InterruptedException e) { Thread.currentThread().interrupt(); throw new IOException("下载被中断", e); } } }这个算法按累计写入字节推算期望耗时，实际耗时不够就sleep补上，不需要引入令牌桶之类的重量级依赖。它按单连接限速，用户开多个连接仍能绕过，生产上更严格的做法是在网关层做IP维度限速，但对内部系统来说，单连接限速已经够用，而且改动不超过十行代码。
5. 接上MinIO/OSS以后，下载的思路要从"拉文件"变成"分流"
5.1 预签名URL：让客户端直接找存储要文件
Spring Boot很多项目里的文件其实存在MinIO或者阿里云OSS上，本地磁盘反而没有完整文件。这种场景如果还用Controller去对象存储把文件拉回来再吐给浏览器，就出现了一个经典的性能浪费：文件数据在网络上多绕了一圈，应用服务器的带宽、CPU、内存全被无谓消耗。
对象存储普遍支持预签名URL。服务端给客户端生成一个带时效的GET链接，浏览器直接朝这个链接发起请求，文件完全不经过应用服务器：
@GetMapping("/minio/presigned/{objectName}") public String presignedUrl(@PathVariable String objectName, @RequestParam(defaultValue = "300") int expires) throws Exception { return minioClient.getPresignedObjectUrl( GetPresignedObjectUrlArgs.builder() .method(Method.GET) .bucket(BUCKET_NAME) .object(objectName) .expiry(expires) .build()); }OSS的写法也类似，用generatePresignedUrl，传bucket、object和时间。这种做法有三个好处：应用服务器零下载流量、对象存储自带多线程与限速策略、URL过期自动失效相当于天然的防盗链。但它有一个硬前提：客户端网络必须能直连对象存储地址。很多企业里MinIO部署在内网，客户端在公网，预签名URL生成出来客户端根本访问不到，这种情况只能用下面的代理流式方案。
5.2 代理流式：文件不过内存、只过服务器
当对象存储对客户端不可直接访问时，Controller就退化成"代理下载"。注意这里的实现要点还是那句老话：别把整个对象读进内存。
MinIO的Java SDK里，minioClient.getObject返回的GetObjectResponse本身就是InputStream的子类，可以直接transferTo到响应的OutputStream上：
@GetMapping("/minio/download/{objectName}") public void downloadFromMinio(@PathVariable String objectName, HttpServletResponse response) throws Exception { GetObjectResponse object = minioClient.getObject( GetObjectArgs.builder() .bucket(BUCKET_NAME) .object(objectName) .build()); response.setContentType(MediaType.APPLICATION_OCTET_STREAM_VALUE); String originalName = objectName.contains("/") ? objectName.substring(objectName.lastIndexOf("/") + 1) : objectName; response.setHeader(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename*=UTF-8''" + encodeFileName(originalName)); object.transferTo(response.getOutputStream()); }这里有个小坑：objectName在MinIO里经常带目录前缀，比如2023/12/report.pdf。如果直接把整个objectName拼进filename*，客户端下载下来的文件名就会带着斜杠前缀和目录结构，难看且容易让前端解析出错，所以传输之前要先截取最后一段路径作为真实文件名。
如果你用的是阿里云OSS，对应的是ossClient.getObject(bucket, key)返回的OSSObject，处理思路一样。
5.3 服务间传递MultipartFile：RestTemplate的正确姿势
热搜词里有一个"springboot中mutipart如何用resttemplate传"，虽然说的是上传不是下载，但跟文件流转强相关，顺手把坑也填了。MultipartFile本身不是可序列化的对象，直接用RestTemplate.postForEntity传会报错或者丢失文件名。最常见做法是把文件内容包成ByteArrayResource，并overridegetFilename方法：
@PostMapping("/forward-upload") public String forwardUpload(@RequestParam("file") MultipartFile file) throws IOException { HttpHeaders headers = new HttpHeaders(); headers.setContentType(MediaType.MULTIPART_FORM_DATA); MultiValueMap<String, Object> body = new LinkedMultiValueMap<>(); ByteArrayResource resource = new ByteArrayResource(file.getBytes()) { @Override public String getFilename() { return file.getOriginalFilename(); } }; body.add("file", resource); HttpEntity<MultiValueMap<String, Object>> requestEntity = new HttpEntity<>(body, headers); return restTemplate.postForObject("http://target-service/api/upload", requestEntity, String.class); }RestTemplate默认注册了FormHttpMessageConverter，它会把MultiValueMap里的Resource对象转成multipart/form-data请求体；ByteArrayResource里必须重写getFilename，否则对方服务拿到的是没有文件名的空壳part，一些校验严谨的后端会直接拒绝。
6. 下载接口的安全红线：路径穿越、越权与文件类型
6.1 目录穿越：拼路径前先normalize
前面提过new File("/data/files/" + filename)是典型漏洞。更规整的防护是这样：
Path basePath = Paths.get(UPLOAD_DIR).toAbsolutePath().normalize(); Path filePath = basePath.resolve(filename).normalize(); if (!filePath.startsWith(basePath)) { throw new IllegalArgumentException("非法的文件路径"); }关键在于先normalize再判断。resolve("../../etc/passwd")之后如果不normalize，路径字符串还带着..，startsWith判断很容易被绕过；normalize之后..被真正解析掉，再判断前缀就靠谱了。还有一个容易踩的坑：Windows和Linux的路径分隔符不一样，Windows下是\，判断时最好统一交给Path处理，别用字符串replaceAll去手工拼，手工拼很容易拼出漏洞也容易拼出bug。
6.2 文件类型：attachment兜底，扩展名白名单
有人为了让PDF能在浏览器预览，把所有文件都设成inline，然后被HTML、SVG文件坑了——这两种文件里可以嵌脚本，从你的域名下发HTML内容等于帮攻击者绕过了同源策略，这是存储型XSS的变体。稳妥做法是：下载接口默认全部走attachment强制下载，任何类型都不让浏览器渲染；如果确实需要在线预览PDF、图片，再单独开一个预览接口，并且只对白名单内的扩展名放行：
private static final Set<String> PREVIEW_EXTENSIONS = Set.of("pdf", "jpg", "jpeg", "png", "gif", "webp"); private boolean allowPreview(String filename) { String ext = filename.substring(filename.lastIndexOf('.') + 1).toLowerCase(); return PREVIEW_EXTENSIONS.contains(ext); }扩展名判断别漏了大小写问题。PDF写成.PDF也要能放行，统一toLowerCase()再比对。另外，扩展名校验只能作为辅助，真正决定行为的还是响应头的Content-Disposition和Content-Type，这两个头必须由后端自己控制，永远不要信任前端传过来的文件名或类型。
6.3 鉴权顺序与越权防护
下载接口最容易出现的业务漏洞是越权下载：用户改URL里的文件名或文件ID去下别人的报告、别人的附件。鉴权必须放在打开文件、生成下载响应之前，并且要做细粒度的归属校验，不能只判断"登录没登录"。最粗的模型是"文件ID + 当前用户ID"联合查询：拿到记录才允许下发，拿不到直接返回404，不要返回403，避免暴露文件是否存在的信息。
如果走了对象存储预签名URL，还有一个额外的越权风险点：签名URL一旦发出，拿到链接的人都能下载。所以生成预签名URL之前同样要做权限校验，过期时间尽量短。能5分钟就不10分钟，能在网关层或对象存储侧做Referer校验就加上，别图省事给24小时。
7. 联调时高频踩到的四个坑，提前打好补丁
7.1 前端responseType: 'blob'却收到JSON错误
前端用axios下载文件时一般会设置responseType: 'blob'，结果后端一旦返回业务错误，前端收到的就是一坨Blob，里面的内容实际是JSON字符串。处理方式很简单，下载响应拿到后先看类型：
const res = await axios.get('/api/download', { responseType: 'blob' }); if (res.data instanceof Blob && res.data.type && res.data.type.includes('application/json')) { const text = await res.data.text(); const error = JSON.parse(text); console.error(error.message); return; } const blob = new Blob([res.data]); // 创建 <a> 标签触发下载这个判断建议封装成公共工具函数。不然每个下载按钮的报错提示都会变成"文件已损坏"这类让人摸不着头脑的话，排障时白白浪费半天。
7.2 文件内容拿到了，文件名却读不到
前面讲了Access-Control-Expose-Headers的问题。前端从Content-Disposition解析文件名时还会遇到第二个问题：多次编码。如果后端已经用URLEncoder编了一次，前端拿到的是%25E4%25B8%25AD...，这就是二次编码的典型症状。解决方案是统一约定：后端只编码一次，前端解析时用decodeURIComponent解一次，不要再调encodeURIComponent。约定的东西最好写进接口文档，不然前后端各自"好心"地多转一次，乱码问题能循环出现。
7.3 文件名里的时间戳与浏览器缓存
有些下载文件的文件名带日期，比如日报-2025-04-01.xlsx。浏览器会按URL缓存，同一天下载内容相同的文件，用户二次点击时浏览器可能复用旧响应。如果是动态生成的报表，给响应头加Cache-Control: no-store，让浏览器完全不要缓存；如果是静态文件，反过来要利用缓存让304生效，别一刀切禁掉：
response.setHeader(HttpHeaders.CACHE_CONTROL, "no-store");这里的判断标准就一条：这个文件内容会不会随时间变化。会变就禁缓存，不会变就敞开缓存，别混着来。
7.4 Excel导出这类异步任务，别让HTTP请求等太久
下载功能里很大一类是"导出Excel/报表"，数据量大时同步生成可能让请求等几十秒甚至超时。通用的成熟模式是三步：第一步，提交导出任务返回taskId；第二步，后台线程生成文件到临时目录或者对象存储；第三步，前端轮询taskId状态，文件就绪后用下载接口取文件。另外，临时文件记得做定时清理，我见过因为导出临时文件不清理、把磁盘打满的项目。清理策略一般按"创建时间+N天"定期删除，或者干脆用对象存储自带的生命周期规则。异步导出加定期清理这两件事，看着不起眼，但缺一个都会在生产环境出问题。
文件下载这个功能，表面上是"把字节流还给客户端"六个字，真正落地时牵扯内存模型、HTTP语义、编码规则、对象存储、安全边界一长串细节。我的体会是，只要把上面这四层设计决策先定下来，再动手写代码，大部分坑都能在设计阶段避开；剩下的少数坑，像Range头重复、二次编码、跨域读不到文件名，都属于踩过一次就长记性的类型，希望这篇能帮你提前把这些教训都领走。
