Java HttpServletResponse多文件下载：ZIP流式打包

上周帮一位做后台管理系统的朋友排查问题需求朴素得不能再朴素列表页勾选十来条记录点一下“批量下载附件”浏览器要把十几个文件一次性存到本地。他写了个 for 循环循环里反复调response.getOutputStream()本地跑的时候最后一个文件确实下来了他以为至少成功了一半一上测试环境前端直接提示下载失败后台日志干干净净连异常都没有。这就是典型的Java HttpServletResponse 多文件下载场景里最容易踩的第一个坑——HTTP 响应体在语义上只有一份你不能像往本地文件夹里复制文件那样往同一个响应里连续塞十个独立文件。这篇内容我打算把这件事彻底讲透从“为什么不能直接循环写”讲到“多文件下载到底有哪几种落地形态”再把 ZIP 流式打包、前端多请求、合并成单文件这三条主线的代码骨架、参数选择、编码细节和线上稳定性问题逐一拆开。不管你是刚接需求的后端新人还是写过几年代码但每次遇到中文文件名乱码、大文件 OOM、下载到一半连接被重置就要重新翻文档的老手应该都能从里面抄到可以直接用的东西。1. 先搞清楚一个响应体为什么装不下多个文件1.1 循环写三次只下来一个文件的真实原因HTTP 响应从来就不是“文件夹”它是一个有明确边界的有序字节流。浏览器收到响应后靠三样东西判断内容是什么、存成什么名字、有多大Content-Type告诉它这是 zip 还是图片Content-Disposition告诉它这是内联展示还是作为附件下载、附件叫什么名字Content-Length或者Transfer-Encoding: chunked告诉它边界在哪。你如果在一次响应里先后写进三个 PDF 的字节同时 Disposition只能声明一个文件名浏览器拿到的那一堆字节既不是合法的 PDF 也不是合法的 zip解析失败就丢弃表现出来就是“只有一个文件下来了”或者“下载下来的文件打不开”。更细节一点HttpServletResponse的生命周期是绑在一次请求上的。响应头一旦被提交缓冲区写满、显式 flush、或者流被关闭后续任何setHeader都会静默失败——注意是静默不报错。很多人排查半天以为是响应头没生效其实是提交顺序错了。我用下面这段代码演一遍最常见的事故现场// 错误示范把响应当成文件夹用 for (File f : files) { response.setContentType(application/octet-stream); response.setHeader(Content-Disposition, attachment; filename f.getName()); // 第二次开始全部无效 try (OutputStream out response.getOutputStream()) { // 第二次抛 IllegalStateException Files.copy(f.toPath(), out); } }第一次循环结束时getOutputStream()拿到的流被 try-with-resources 关闭响应随之提交第二次再调getOutputStream()Servlet 规范允许容器抛IllegalStateException也可能因为缓冲区行为不同而把数据写进已经提交的响应里于是前端看到的是一个被拼接坏的字节流。所以结论很干脆想在一个 HTTP 响应里交付多个文件必须先把它们“装进一个容器”这个容器可能是 ZIP 包、可能是合并后的单个文档、也可能压根不是容器而是拆成多次 HTTP 请求。1.2 四种落地形态的选型对照在动手写代码之前先花五分钟把方案选对后面能省掉大量返工。我把实际项目里见过的做法归成四类各自的适用边界差别很大方案交付形态用户操作次数适合的文件量主要代价ZIP 流式打包一个 zip 文件1 次任意数量单包建议 ≤ 2GB需要压缩前端拿到的是压缩包前端并发多请求N 个独立文件1 次点击、N 次请求≤ 20 个单个不宜过大浏览器可能拦截需要排队控制合并成单文档一个 PDF / Excel1 次文档类内容只适合同类文档格式受限服务端生成清单分包N 个 zip 包N 次点击超大集合如整个项目资料交互复杂需要分页下载选型的判断逻辑其实很直接。如果文件本身是异构的有图有表有文档、数量不确定、单个文件可能几十上百兆ZIP 是默认答案用户的接受度也最高因为他拿到的是一个完整的“压缩包”心智模型。如果文件数量很少、单个又特别大比如几个 800MB 的视频素材打包反而让用户多等一轮压缩这时候前端并发多请求更合适。如果业务本质上是“把一堆数据导出成一份报表”那根本不该走多文件下载直接合并成一个 Excel 工作簿或者一份 PDF 才是正解。至于第四种本质上是前三种的分页组合属于产品交互层面的设计技术上没有新东西。提示选型时先问一句“用户拿到东西之后准备干什么”。如果他要解压后逐个打开看ZIP 没问题如果他要直接拖进某个软件批处理那独立文件更友好如果他要打印或归档合并成单文档最省事。技术方案跟着使用场景走别反过来。2. ZIP 流式打包多文件下载的主力方案2.1 响应头的顺序与参数怎么定ZIP 方案的完整链路是客户端发一次请求 → 服务端建一个ZipOutputStream直接套在response.getOutputStream()上 → 边读源文件边写 ZIP 条目 → 关闭流。整个过程不落盘内存占用只跟缓冲区大小有关这是它比“先打包到临时文件再回传”优秀的地方。但流式也有代价一旦开始写响应体你就失去了中途改主意的机会出错也来不及给用户一个友好的错误页只能断开连接。所以所有校验必须前置。响应头的设置顺序我习惯按这个套路写先response.reset()清掉可能存在的历史状态尤其是经过拦截器、过滤器之后再设字符编码再设Content-Type再设Content-Disposition最后按需设Content-Length。字符编码必须在getOutputStream()之前定否则容器可能已经用默认编码初始化了 writer。ZIP 场景下Content-Type一般用application/zip有些老系统会写application/octet-stream强制下载两者都能工作前者语义更准确。Content-Length在流式打包时是算不出来的因为压缩率未知这时候不要硬设让容器用 chunked 传输编码即可硬设一个错的值会导致浏览器提前判定“下载完成”文件被截断这是线上非常隐蔽的一类故障。response.reset(); response.setCharacterEncoding(UTF-8); response.setContentType(application/zip); response.setHeader(Content-Disposition, buildContentDisposition(zipName)); response.setHeader(Cache-Control, no-store); response.setHeader(X-Content-Type-Options, nosniff);Cache-Control: no-store这一行经常被忽略。批量下载往往携带用户身份和数据权限某些浏览器或者中间的缓存层有机会把响应留下来下次另一个用户请求同一个 URL 拿到上一份数据这种事故排查起来非常麻烦。X-Content-Type-Options: nosniff是防御性的避免浏览器自作聪明猜测类型。这两个头不占成本加上就是。2.2 从响应头到流关闭的完整代码骨架下面这份代码骨架是我在多个项目里反复改出来的版本去掉业务耦合之后大概长这样。它处理了空集合、条目重名、单文件读取异常不中断整体、以及流的正确收尾public void writeZip(HttpServletResponse response, ListFileItem items, String zipName) throws IOException { // 1. 前置校验没有任何可下载内容时返回 404 而不是空 zip if (items null || items.isEmpty()) { response.sendError(HttpServletResponse.SC_NOT_FOUND, no files); return; } // 2. 响应头 response.reset(); response.setCharacterEncoding(UTF-8); response.setContentType(application/zip); response.setHeader(Content-Disposition, buildContentDisposition(zipName)); response.setHeader(Cache-Control, no-store); response.setHeader(X-Content-Type-Options, nosniff); // 3. 流式写入 ZipOutputStream zos new ZipOutputStream(response.getOutputStream(), StandardCharsets.UTF_8); zos.setLevel(Deflater.DEFAULT_COMPRESSION); byte[] buf new byte[16 * 1024]; SetString usedNames new HashSet(); try { for (FileItem item : items) { String entryName dedup(item.getName(), usedNames); ZipEntry entry new ZipEntry(entryName); entry.setTime(item.getLastModified()); zos.putNextEntry(entry); try (InputStream in item.openStream()) { int len; while ((len in.read(buf)) ! -1) { zos.write(buf, 0, len); } } catch (IOException readErr) { // 单个文件读失败记日志写入一个说明文件继续下一个 log.warn(read failed: {}, entryName, readErr); zos.write((文件 [ entryName ] 读取失败请联系管理员) .getBytes(StandardCharsets.UTF_8)); } zos.closeEntry(); } } finally { try { zos.finish(); // 写出 ZIP 中央目录缺了它文件就是坏的 } finally { zos.close(); // 关闭会连带 flush 响应流 } } }几个关键点在代码里都用注释标了我展开说两个。第一是zos.finish()。ZIP 格式的末尾有一段叫中央目录的结构记录所有条目的偏移量和元信息解压软件靠它才能正确列出内容。如果你只closeEntry()而不finish()或者异常路径里直接把流关了出来的文件大小看起来正常但双击打开会提示“压缩包损坏”。这是 ZIP 方案最高频的 bug而且只在异常路径下出现正常测试很难发现。第二是dedup方法同名条目在 ZIP 里是允许的但解压工具的行为不一致有的报错、有的覆盖、有的自动改名用户体验很糟。我一般是发现重名就追加(1)、(2)后缀简单可靠。buildContentDisposition和dedup两个小工具方法private String buildContentDisposition(String fileName) throws UnsupportedEncodingException { String encoded URLEncoder.encode(fileName, UTF-8).replace(, %20); return attachment; filename\ encoded \; filename*UTF-8 encoded; } private String dedup(String rawName, SetString used) { String name sanitize(rawName); // 去掉路径分隔符等危险字符 if (used.add(name)) return name; int dot name.lastIndexOf(.); String base dot 0 ? name.substring(0, dot) : name; String ext dot 0 ? name.substring(dot) : ; for (int i 1; ; i) { String candidate base ( i ) ext; if (used.add(candidate)) return candidate; } }2.3 中文文件名的两道编码坎只要是中文项目这一节基本躲不掉。RFC 2616 时代Content-Disposition的filename参数按规范只接受 ISO-8859-1 字符集中文塞进去要么乱码要么被容器拒绝。RFC 5987 之后有了filename*UTF-8这个扩展语法现代浏览器都支持但仍有部分老旧客户端只认filename。所以稳妥做法是两个都写filename放一份 URL 编码后的值给老客户端兜底filename*放标准编码给新客户端优先取用。这里有个细节值得强调URLEncoder.encode会把空格编码成而在 URL 查询串里表示空格在filename参数里却就是字面的加号。所以必须把替换成%20否则用户下载下来看到的是附件打包.zip。同理URLEncoder会保留*、-、_、.这几个字符不编码一般无害但如果文件名里含单引号filename*语法里的分隔符会被破坏保险起见把单引号也换成%27。还有一个更隐蔽的坑如果你用的是 Spring 的ContentDisposition构建器ContentDisposition.attachment().filename(name, StandardCharsets.UTF_8).build()它在某些版本里会自动处理编码你再去手工编码一次就会双重编码前端显示成%E9%99%84%E4%BB%B6.zip这种一串百分号。判断办法很简单用浏览器开发者工具看响应头原文如果filename*里已经是%E9%99%84开头说明编码正确如果看到%25E9那就是双重编码。这个坑我在两个项目里各踩过一次第二次还是踩了所以现在养成习惯写完下载接口一定用 curl 看一眼响应头。curl -sI -X POST http://localhost:8080/api/files/batch \ -H Content-Type: application/json \ -d {ids:[1,2,3]} | grep -i content-disposition2.4 ZipOutputStream 里最容易翻车的四个细节第一个是不要复用ZipEntry对象。putNextEntry之后 entry 的内部状态会被流改写同一个 entry 实例塞第二次会抛ZipException: duplicate entry或者更诡异地把上一个文件的内容带进去。每次循环新建一个成本可以忽略。第二个是压缩级别别乱调。setLevel(Deflater.NO_COMPRESSION)在某些场景下是正解比如打包的文件本身已经是 jpg、mp4、zip 这类压缩过的格式再压一遍既费 CPU 又几乎没收益我实测过一个由 200 张 3MB 图片组成的包默认压缩级别下打包耗时 8.4 秒设成NO_COMPRESSION后降到 1.2 秒包体积只大了 0.7%。反过来如果是 txt、csv、xml 这类文本默认级别能压到原体积的三分之一值得压。所以成熟的实现会按文件扩展名动态决定 level虽然 ZIP 规范里 level 是流级别的但你可以简单点整包按“是否含大量已压缩格式”来决定。第三个是缓冲区大小。默认ZipOutputStream内部缓冲 512 字节太小了。外面套一层BufferedOutputStream或者自己用 16KB、32KB 的 byte 数组读源文件能明显减少系统调用次数。我给一个粗略的量级参考8KB 缓冲区在千兆内网下大概能跑到 80MB/s 左右调到 32KB 能上到 200MB/s 以上再往上收益递减。别一上来就 1MB那对内存不友好尤其是并发下载的场景。第四个是异常处理不能简单吞掉。流式响应已经开始写了客户端那边可能已经弹出了下载进度条这时候抛异常浏览器大概率显示“下载失败”而不是你精心准备的错误提示。所以对单个文件读取失败我的处理是降级成写一个说明文本进包然后继续对致命错误比如磁盘挂了才中断并在日志里明确记录是第几个条目出的问题方便事后补偿。同时记得finally里的finish()和close()都要加 try 包住否则finish()失败会让close()被跳过连接泄漏。3. 前端多次请求不走打包的另一条路3.1 浏览器对连续下载的限制到底在哪很多同学以为浏览器会拦截“多文件下载”这个说法不准确。浏览器拦的是非用户手势触发的、或者过于频繁的下载行为。用户点一次按钮前端在回调里连续创建多个a download并触发 clickChrome 通常只放行第一个后面的会被静默忽略并在地址栏右侧提示“已阻止多个文件下载”。这是防滥用机制不是 bug你没法通过改代码绕过。突破口有两个方向。一是让每次下载之间必须有独立的用户手势也就是把“一键下载全部”改成“逐个点击”体验很差一般不采用。二是用fetch把文件先取成Blob再用URL.createObjectURL触发单个a[download]这种做法在用户手势的同一个调用栈里完成浏览器认为是同一个下载动作不会被拦。代价是所有文件的内容都要先过一遍内存大文件会直接把标签页撑爆。实践中的折中方案是数量少、体积小走 Blob数量多、体积大老老实实走 ZIP。3.2 三种前端触发方式的实测差异我把常见的三种写法放在一起对比这是本地和线上都验证过的结论方式是否受多文件限制能否拿到文件名大文件表现适用场景window.open(url)受拦截靠响应头容器自行流式内存友好单个大文件隐藏iframe部分受拦截靠响应头同上老系统兼容a download 直接 href受拦截可指定同上单文件fetchBloba[download]不受拦截可解析响应头全部进内存慎用≤ 10 个小文件iframe方式值得一提它的好处是浏览器原生处理下载不需要读取响应体服务端那边看到的就是一次普通的 GET 请求流式输出完全不受影响。缺点是你拿不到下载完成的事件做不了“全部完成”的提示也不方便做错误处理——如果服务端返回了 500iframe 里悄悄加载一个错误页用户完全无感知。所以我只在明确不需要反馈的后台工具里用它。3.3 前端排队与失败重试的实现细节真要在前端做多文件下载我建议加一层串行队列别一口气并发十个请求。原因很实际并发请求会同时占用服务端连接数十几个大文件一起下载用户自己的带宽被打满每个文件都变得极慢PC 端可能还没事移动端直接就超时了。串行的做法很简单用一个 async 函数配合 for 循环每下载完一个就更新进度文案用户能看到“正在下载 3/10”心理感受好很多。async function downloadSerial(ids, onProgress) { for (let i 0; i ids.length; i) { onProgress(i 1, ids.length); const resp await fetch(/api/files/ ids[i], { credentials: same-origin }); if (!resp.ok) { console.warn(skip, ids[i], resp.status); continue; // 单个失败不阻断整体 } const blob await resp.blob(); const cd resp.headers.get(Content-Disposition) || ; const name decodeURIComponent( (cd.match(/filename\*UTF-8([^;])/) || [])[1] || (file- ids[i]) ); const url URL.createObjectURL(blob); const a document.createElement(a); a.href url; a.download name; document.body.appendChild(a); a.click(); a.remove(); setTimeout(() URL.revokeObjectURL(url), 30000); // 延迟释放避免下载被掐断 } }两个经验点。一是URL.revokeObjectURL不能紧跟在click()后面调某些浏览器在下载真正开始之前对象 URL 就失效了结果是下载 0 字节延迟几十秒释放最稳。二是resp.headers.get(Content-Disposition)在跨域场景下默认读不到需要服务端加Access-Control-Expose-Headers: Content-Disposition。同源部署一般不会遇到但前后端分离的项目十有八九会在这里卡一阵。注意fetch拿不到下载进度blob()是一次性完成的。如果你的用户真的需要进度条只能上ReadableStream手动读Content-Length计算百分比或者干脆回到 ZIP 方案让浏览器原生显示进度。别为了一个进度条把架构搞复杂。4. 变通方案把多个文件变成“一个文件”4.1 多份 Excel 合并成一个工作簿报表导出是这类需求的高发区。业务方说要“下载这 20 个部门的月度报表”你要是真给他一个 zip他下一秒就会问能不能合成一个。这时候正确的做法是在服务端合并用 POI 的SXSSFWorkbook而不是XSSFWorkbook。区别很关键XSSFWorkbook把所有行都放在内存里一份十万行的表就能吃掉几百兆堆内存二十个部门一起合并基本必 OOMSXSSFWorkbook会把滑动窗口之外的行刷到磁盘临时文件内存占用跟窗口大小相关默认窗口 100 行设成 500 到 1000 是比较好的平衡点。合并的时候按 sheet 拆分一个部门一个 sheetsheet 名就是部门名。这里有个容易被忽略的限制sheet 名不能超过 31 个字符不能包含: \ / ? * [ ]这些字符而且不能重名。业务方的部门名里带斜杠、带方括号的情况我见过不止一次直接createSheet就抛IllegalArgumentException。稳妥的写法是先做一遍字符替换再做长度截断重名的时候追加序号。写完之后记得调workbook.dispose()清理临时文件否则/tmp目录会被悄悄撑满这个故障通常在一两周后才爆发排查起来毫无头绪。4.2 多张图片合成一份 PDF 或长图图片批量下载的需求也不少比如某高校实验室要导出实验过程的照片存档某内容平台要导出文章配图。直接 ZIP 当然可以但如果目的是打印或传阅合成 PDF 体验好得多。技术上用 PDF 库每张图一页页尺寸按图片比例换算成标准纸张尺寸边距留一点图片居中。要注意图片方向手机拍的照片带 EXIF 旋转信息直接读像素画进 PDF 会是横躺的得先把 EXIF 里的 orientation 读出来做一次仿射变换。如果只是想在网页里展示可以合成长图用Graphics2D拼一张大图。这里要提醒一句风险拼长图是把所有图片解码后放在同一个BufferedImage里十张 4000×3000 的照片拼起来就是几亿像素堆内存瞬间崩掉。我的做法是先统一缩放到宽度 1080再纵向拼接输出 JPEG质量和体积都可控。这个操作必须在服务端做别指望浏览器手机端分分钟白屏。4.3 什么场景下别硬合并合并方案好用但有三类场景我劝你别用。第一类是文件类型完全不同把 PDF、Excel、图片硬塞进一个 PDF用户拿到只会觉得莫名其妙。第二类是文件之间需要独立流转比如合同附件要分别发给不同的人合并后还得拆开纯属给下游添麻烦。第三类是单个文件本身就很大合并后的产物可能超过邮件附件的体积上限也不方便用浏览器打开预览。判断标准还是那句跟着用户拿到文件之后的行为走别为了技术上的省事牺牲使用体验。5. 大文件与高并发下的稳定性处理5.1 内存打包与磁盘临时文件的分界线流式 ZIP 是首选但有些场景它会失效比如你需要给 ZIP 包加密、需要计算整个包的校验和、或者需要在响应头里给出准确的Content-Length。这时候就得先打包到临时文件再回传。什么时候值得切换到落盘模式我给自己定的经验值是单次打包体积预期超过 500MB或者客户端明确要求显示总进度就考虑落盘。落盘模式的坑集中在临时文件管理上。文件要建在配置好的临时目录里别用System.getProperty(java.io.tmpdir)直接拼那个目录可能挂载在一个容量很小或者 IO 很慢的分区上。文件名用 UUID绝不能用用户传进来的名字否则就是一个路径穿越漏洞。用完必须在finally里删而且删除操作本身也可能失败Windows 上文件被占用删不掉要记日志并依赖定时清理任务兜底。我在一个项目里见过临时目录积累了 3 万多个废弃 zip占了 40 多 GB起因就是某次代码重构把finally里的删除逻辑弄丢了两个多月没人发现。内存和磁盘的取舍还有一个中间态值得说控制单次打包的条目数。与其纠结用内存还是磁盘不如从产品层面限制一次能选多少个文件比如限制 50 个超出提示分批下载。这一条限制能挡住绝大部分极端情况而且用户完全可以接受。5.2 异步流式输出与容器线程的释放同步 Servlet 模式下一个下载请求会长时间占用一个容器工作线程。默认线程池也就两百个左右如果有几十个人同时在下载大包其他请求就开始排队表现为整个站点变慢。这就是“下载拖垮全站”的经典剧本。Servlet 3.1 之后可以用异步模式把写流的工作扔到业务线程池容器线程立刻归还。Spring MVC 里的StreamingResponseBody就是这层能力的封装用起来很简单GetMapping(/api/files/batch/stream) public ResponseEntityStreamingResponseBody stream(RequestParam ListLong ids) { StreamingResponseBody body out - { try (ZipOutputStream zos new ZipOutputStream(out, StandardCharsets.UTF_8)) { for (Long id : ids) { FileItem item fileService.load(id); zos.putNextEntry(new ZipEntry(item.getName())); item.transferTo(zos); zos.closeEntry(); } zos.finish(); } }; return ResponseEntity.ok() .contentType(MediaType.parseMediaType(application/zip)) .header(HttpHeaders.CONTENT_DISPOSITION, buildContentDisposition(附件打包.zip)) .body(body); }用异步的时候有个额外要求线程池要单独配置别跟业务逻辑用同一个。下载线程的存活时间可能是几分钟扔进业务线程池会把在线请求的线程抢光等于没解决问题。一般给下载单独配一个核心 4、最大 16、队列有界的池子队列满了直接拒绝并提示稍后再试比无限排队最后全部超时体面得多。5.3 网关缓冲、超时与连接重置服务端写得好好的前面挂一层反向代理问题就来了。默认的代理配置往往是“先把上游响应完整收下来再转发给客户端”对大文件来说这意味着代理节点上要先缓存整个包缓存目录撑爆、转发延迟巨大、客户端早超时了。解决办法是关掉代理缓冲不同代理参数名不同常见的是关闭 response buffering让字节流直接透传。超时是另一个隐形杀手。代理的读超时、容器的连接超时、客户端的请求超时三个时间必须协调。我的配置原则是代理读超时 服务端最长允许的打包时间 客户端超时逐层递减但留足余量。实际配的时候经常出问题的是中间那层代理的默认 60 秒读超时一个 800MB 的包在内网也要几十秒稍微慢一点就被代理掐断客户端看到的就是“下载到 87% 突然失败”。这类问题的排查特征是服务端日志正常写完了整个包客户端却报错看代理的访问日志能看到 502 或者 504。还有一个容易忽视的点是客户端主动取消。用户点了下载又点了取消或者直接关了页面服务端还在傻乎乎地读磁盘写流写到一个已经关闭的连接上会抛ClientAbortException。这个异常在日志里很吵但不该当成错误处理更不该回滚什么业务数据。我的做法是在写流的循环里 catch 到这类异常后直接返回日志级别降到 debug。如果你们的日志平台对异常特别敏感可以加个判断过滤掉。6. 高频问题排查速查6.1 现象、根因与处理对照表现象常见根因处理方式只下来最后一个文件一次响应里循环写多个文件改 ZIP 或前端多请求压缩包能下载但打不开提示损坏缺finish()或异常路径未收尾finally 中 finish close中文文件名变成百分号串双重编码只用一套编码逻辑看响应头原文文件名变成号URLEncoder把空格编成替换成%20文件 0 字节响应头设置时已提交或流未 flush先设头再取流结尾 flush下载到一半失败代理读超时 / 客户端超时调大超时关代理缓冲大文件下载必 OOM内存中聚合全部字节改流式检查是否用了toByteArray日志刷满ClientAbortException用户取消下载降级为 debug不做业务回滚前端点击无反应被浏览器多文件下载限制拦截改 ZIP或串行 Blob 方案偶发下载到别人的文件缓存头缺失 / 路径拼接错误加no-store校验资源归属6.2 从现象到根因的四步定位法遇到“下载不对”的问题我一般按这个顺序查能覆盖八成情况。第一步看响应头用浏览器开发者工具或者 curl 拿到原始的Content-Type、Content-Disposition、Content-Length、Transfer-Encoding先确认服务端有没有按预期设置。这一步能解决编码问题和类型问题。第二步看字节数把下载下来的文件和源文件比大小如果小了一截问题在写入过程被截断往超时和缓冲区方向查如果大小一样但打不开问题在内容拼接或格式头往finish()、closeEntry()方向查。第三步看服务端日志确认代码有没有走完正常路径有没有吞掉的异常。第四步才看网络链路代理、负载均衡、CDN 一层层排除。这个顺序的道理是从最接近问题的地方开始。多人协作时常见的低效排查是后端说“我这边日志正常”前端说“我这边请求成功但文件不对”然后两边互相等。这时候把响应头截个图发群里往往五分钟就定位了。6.3 安全底线路径穿越与越权下载下载接口是安全事故的高发区两个点必须守住。第一个是路径穿越。如果接口接受文件名参数去拼路径用户传个../../../../etc/passwd你可能就把系统文件送出去了。防御手段是只用 ID 查询不要用文件名拼路径如果必须用文件名做规范化后校验前缀是否在允许目录内。Path base Paths.get(uploadDir).toRealPath(); Path target base.resolve(userInput).normalize().toRealPath(); if (!target.startsWith(base)) { throw new SecurityException(illegal path); }第二个是越权。批量下载尤其危险因为一次请求带多个 ID很容易漏掉某个 ID 的归属校验。正确的做法是查出来之后逐条比对当前登录用户任何一条不通过就整体拒绝而不是“跳过无权的继续下载”——后者看起来友好实际上泄露了“这个 ID 是存在的”这一信息。另外附件下载最好走一次性的短时效 token把鉴权和取流分开避免下载链接被复制传播。7. 几条踩出来的实操经验关于缓冲区大小我最后再强调一次别小看这个数字。默认的 512 字节在本地测没问题一上生产同样一个 500MB 的包8KB 缓冲能跑完512 字节的可能因为系统调用太密集导致 CPU 打满、进度像蜗牛。我一般的配置是源文件读取缓冲 32KBZIP 流外面不额外套BufferedOutputStreamZIP 内部已经有一层了套多了反而增加一次拷贝响应输出交给容器自己的缓冲区。关于测试光在本地用 Postman 点一下“下载”是不够的。至少要做三件事一是用curl -o下载后比对 MD5确认字节完全一致二是在下载过程中手动断网或者按取消看服务端日志和线程状态是否干净三是把并发调上去同时开 20 个下载观察其他普通接口的响应时间有没有明显劣化。这三步能提前发现绝大部分线上问题成本也就半小时。关于命名给用户的压缩包名字里带上时间戳是非常实用的小细节比如附件打包_202405171030.zip用户下载十个包放在桌面也不会混淆。但注意别用冒号Windows 不允许文件名含冒号SimpleDateFormat里的HH:mm:ss如果直接拼进去用户在 Mac 上下载好好的Windows 用户解压出来文件名会变形。用yyyyMMddHHmmss就没有这个问题。最后说一句关于“够用”的判断。多文件下载这件事从技术上看方案很多但落到具体项目里绝大多数情况下 ZIP 流式打包 中文名双写 前置权限校验这三件事做扎实就已经覆盖 95% 的需求了。剩下的 5% 是超大体积、特殊格式、特殊交互等真的遇到了再针对性优化不要一上来就把所有方案都实现一遍那样维护成本会比问题本身还高。