压缩流 ZipOutputStream：实战多文件打包压缩中的变量条目 ZipEntry 管理逻辑

先说几个核心判断：ZipOutputStream 真正决定压缩包内部结构的，不是文件本身，而是每个 ZipEntry 实例所携带的路径名和元信息。它不会自动去读取源文件的系统路径，也不会校验条目是否重复或冲突——所有条目的管理逻辑，都得你亲自上手，显式控制。

ZipEntry 的名称就是解压后的相对路径

ZipEntry 构造时传入的那个字符串，会直接成为 ZIP 包内该文件的完整路径（含目录层级）。举个例子就清楚了：

• new ZipEntry("report/summary.pdf") → 解压后生成 report/summary.pdf
• new ZipEntry("img/logo.png") → 解压后生成 img/logo.png
• new ZipEntry("config/") → 表示空目录（末尾斜杠不可省）

这里需要留个心眼：不能含盘符（比如 C:\），也不能含 ../ 这种上级跳转路径，否则不少解压工具会直接拒绝处理，或者行为异常。

每个文件必须对应一个独立的 putNextEntry + closeEntry 周期

ZipOutputStream 并不支持什么“批量添加”或“延迟写入”——它没那么智能。每写一个文件，必须严格按顺序来：

• 先调用 zos.putNextEntry(entry) —— 开启新条目，同时会自动关闭前一个（如果有的话）
• 再写入该条目的全部字节内容（可以用 Files.copy(file, zos)，或者自己循环 read/write）
• 最后必须调用 zos.closeEntry() —— 这一步一旦遗漏，ZIP 格式可能损坏，多数解压软件都无法识别

遗漏 closeEntry() 是导致 ZIP 打开失败最常见的原因之一，特别是在异常分支里，很容易被忽略。

中文文件名与编码陷阱

ZipOutputStream 默认用 IBM437 编码，直接往里塞中文名，结果大概率是乱码，甚至解压失败。解决方式取决于使用场景：

• 本地保存 ZIP 文件：JDK 7+ 推荐改用 ZipArchiveOutputStream（来自 Apache Commons Compress），并显式设置 setEncoding("UTF-8")
• HTTP 下载响应流：如果坚持用 ZipOutputStream，就需要确保条目名经 UTF-8 编码再转成 IBM437 兼容形式。但要注意，类似 new String(name.getBytes(UTF_8), "GB2312") 这类转换方式已经过时且不可靠，更稳妥的办法是直接换用第三方库

另外，浏览器下载时，中文压缩包名还需要通过 URLEncoder.encode(filename, "UTF-8") 处理 Content-Disposition 头，否则文件名也可能出现乱码。

空目录、重复名、特殊字符的处理原则

ZIP 规范本身允许空目录和同名条目存在，但不同解压工具的实际行为可能差异很大，所以最好主动规避歧义：

• 空目录必须以 / 结尾，且同样需要调用 putNextEntry + closeEntry（只是不写入内容）
• 避免不同文件生成相同的 ZipEntry 名（比如都叫 data.txt），否则后写入的会直接覆盖前一个
• 条目名中尽量避免出现 \、?、*、<、>、| 等 Windows 非法字符——尽管 ZIP 格式本身能存，但一旦解压到 Windows 系统上就会失败

常规做法是统一做一次路径标准化：把反斜杠替换为正斜杠，过滤掉非法字符，对重名文件加序号后缀（比如 file (1).txt）。这样能避免很多意想不到的兼容性问题。