## 📋 目录

- 一、工具类功能
- 二、所需环境
- 三、方法与调用示例（按需调用）
- 四、工具类源码（可直接复制）

## 一、工具类功能

把多个文件或目录递归打包成一个 zip、把 zip 安全解压到指定目录，中文条目名按 UTF-8 写、旧版 Windows 打的包可按 GBK 读，解压自带 Zip Slip 与压缩炸弹防护。

## 二、所需环境

JDK 17或以上

## 三、方法与调用示例（按需调用）

🔢 **方法序号**：1

🎯 **方法用途**：
- 把多个文件和目录递归打进一个 zip，条目名统一按 UTF-8 写
- 不用自己走目录、拼条目名、管流，中文文件名解出来不会乱码

🧩 **方法定义**：`public static void zip(Path zipFile, Path... sources)`

🗣️ **入参解释**：`public static void zip(zip输出路径, 待压缩源文件或目录)`

📤 **返回值解释**：`void`，zip 直接写到 `zipFile` 那个路径上

💡 **边界口径**：
- 目录递归展开，条目名相对各源根目录，目录条目以 `/` 结尾，空目录也留一条目录条目
- 同一目录下的条目按路径排序后写入，包内顺序稳定可复现
- 目录里的符号链接条目一律跳过，既不解析目标也不递归进目录软链
- 输出文件的父目录不存在时自动创建，条目时间取源文件的最后修改时间
- 同一个路径重复当两个源时，JDK 判定重复条目，包一层成 `IllegalStateException`

🧪 **方法示例**：
- `zip(zipFile, reportDir, noteFile)` 拿到一个 `457` 字节的包，目录和散文件一起收进去
- `zip(out.zip, emptyDir, noteFile)` 后 `listEntries(out.zip)` 拿到 `[空目录/, 说明.txt]`，空目录留了目录条目
- `zip(deepOut, noteFile)` 打完再 `Files.exists(deepOut)` 拿到 `true`，中间两层父目录被自动创建
- `zip(zipFile, noteFile, noteFile)` 抛 `IllegalStateException`，消息是「压缩zip失败: duplicate entry: 说明.txt」
- `zip(null, noteFile)` 抛 `IllegalArgumentException: 输出zip路径不能为null`
- `zip(out.zip)` 抛 `IllegalArgumentException: 待压缩源不能为null或空`
- `zip(out.zip, 不存在.txt)` 抛 `IllegalArgumentException`，消息是「待压缩源不存在」再补上当时那个路径
- `zip(out.zip, out.zip)` 抛 `IllegalArgumentException`，消息是「待压缩源不能是输出zip文件本身」再补上路径

---

🔢 **方法序号**：2

🎯 **方法用途**：
- 打包时自己定压缩力度，`0` 只存储、`9` 压到最小、`-1` 交回 JDK 默认
- 大批量已经压过的文件（图片、视频、别的 zip）用 `0`，省掉一遍白费 CPU

🧩 **方法定义**：`public static void zip(Path zipFile, int compressionLevel, Path... sources)`

🗣️ **入参解释**：`public static void zip(zip输出路径, 压缩级别, 待压缩源文件或目录)`

📤 **返回值解释**：`void`，zip 直接写到 `zipFile` 那个路径上

💡 **边界口径**：
- 级别只收 `-1` 与 `0~9`，别的值抛 `IllegalArgumentException`，消息里带上当时的值
- 同一个目录用 `0` 和用 `9` 差得很远，文本类内容实测 `5483` 字节对 `552` 字节
- `-1` 就是方法1 用的那个默认级别，结果一模一样
- 其余口径同方法1

🧪 **方法示例**：
- `zip(out.zip, Deflater.NO_COMPRESSION, reportDir)` 拿到 `5483` 字节的包，只存储不压缩
- `zip(out.zip, Deflater.BEST_COMPRESSION, reportDir)` 拿到同一个目录压出的 `552` 字节
- `zip(out.zip, -1, reportDir)` 拿到 `552` 字节，与默认级别一致
- `zip(out.zip, 99, noteFile)` 抛 `IllegalArgumentException: 压缩级别必须为-1或0~9，当前为99`
- `zip(out.zip, -2, noteFile)` 抛 `IllegalArgumentException: 压缩级别必须为-1或0~9，当前为-2`

---

🔢 **方法序号**：3

🎯 **方法用途**：
- 把一个 zip 解压到指定目录，返回解出来的文件条目数
- 自带 Zip Slip 与压缩炸弹防护，来源不明的包也敢落地

🧩 **方法定义**：`public static int unzip(Path zipFile, Path targetDir)`

🗣️ **入参解释**：`public static int unzip(zip路径, 解压目标目录)`

📤 **返回值解释**：`int`，解压出的文件条目数，目录条目不计

💡 **边界口径**：
- 条目名按 UTF-8 解，上限用默认的 `10000` 个条目与 `512 MiB` 累计字节
- 条目名含 `..`、写成绝对路径或以任何形式跳出目标目录，整包立即拒绝，不落地
- 条目名带目标文件系统不接受的字符（Windows 的 `: < > |"` 等）同样被拒
- 中途失败时已经落盘的文件不会被自动删掉，要调用方自己清理，建议解进空目录
- 目标目录不存在自动创建，重复解压同名文件是覆盖而不是追加

🧪 **方法示例**：
- `unzip(zipFile, targetDir)` 拿到 `2`，落到磁盘的是 `[报表/月度报表.txt, 说明.txt]`，目录条目 `报表/` 不计数
- `unzip(同一个包, 同一个目录)` 连调两次都拿到 `2`，第二次覆盖同名文件
- `unzip(空包, targetDir)` 拿到 `0`，没有任何条目也算成功
- `unzip(穿越包, targetDir)` 抛 `IllegalStateException: 检测到非法zip条目(路径穿越): ../逃出去.txt`
- `unzip(绝对路径包, targetDir)` 抛 `IllegalStateException: 检测到非法zip条目(路径穿越): C:/Windows/temp.txt`
- `unzip(非法名包, targetDir)` 抛 `IllegalStateException: 检测到非法zip条目(条目名含文件系统非法字符): bad:name.txt`
- `unzip(没有.zip, targetDir)` 抛 `IllegalArgumentException`，消息是「zip文件不存在或不是普通文件」再补上路径
- `unzip(zipFile, null)` 抛 `IllegalArgumentException: 目标目录不能为null`

---

🔢 **方法序号**：4

🎯 **方法用途**：
- 解压时指定条目名编码，专治旧版 Windows 自带工具打的 GBK 包
- 编码传错会明确报错并提示实际编码，不会解出一堆乱码文件名

🧩 **方法定义**：`public static int unzip(Path zipFile, Path targetDir, Charset charset)`

🗣️ **入参解释**：`public static int unzip(zip路径, 解压目标目录, 条目名编码)`

📤 **返回值解释**：`int`，解压出的文件条目数，目录条目不计

💡 **边界口径**：
- 包里条目名带 UTF-8 标记时按标记解，没带时才用传入的 `charset`
- 条目名按传入编码解不出来时抛 `IllegalArgumentException`，消息说清用的哪个编码、并提示旧包多半是 GBK
- 条目数与字节上限仍走默认值，要收紧用方法5
- 其余防护与落盘口径同方法3

🧪 **方法示例**：
- `unzip(gbkZip, targetDir, Charset.forName("GBK"))` 拿到 `1`，还原出 `中文清单.txt`
- `unzip(gbkZip, targetDir, StandardCharsets.UTF_8)` 抛 `IllegalArgumentException`，消息是「zip条目名无法按UTF-8解码，该包的条目名可能是别的编码（旧版Windows打的包传GBK）」
- `unzip(zipFile, targetDir, null)` 抛 `IllegalArgumentException: 字符集不能为null`

---

🔢 **方法序号**：5

🎯 **方法用途**：
- 解压时把条目数上限和累计解压字节上限一起收到自己手里
- 收上来的是「最多解多少个文件、最多解出多少字节」，超限直接中止，挡住压缩炸弹

🧩 **方法定义**：`public static int unzip(Path zipFile, Path targetDir, Charset charset, int maxEntries, long maxTotalBytes)`

🗣️ **入参解释**：`public static int unzip(zip路径, 解压目标目录, 条目名编码, 条目数上限, 累计解压字节上限)`

📤 **返回值解释**：`int`，解压出的文件条目数，目录条目不计

💡 **边界口径**：
- 两个上限都必须是正数，`0` 或负数抛 `IllegalArgumentException`，消息带上当时的值
- 条目数超限抛 `IllegalStateException`，消息是「zip条目数超过上限N，疑似压缩炸弹」
- 字节数是边写边累计，超限立刻中止并点名当时那个条目，中止前已写出的文件留在原地
- 方法3 与方法4 用的就是默认的 `10000` 个条目与 `512 MiB`

🧪 **方法示例**：
- `unzip(zipFile, targetDir, StandardCharsets.UTF_8, 10, 1024 * 1024)` 拿到 `2`，上限放宽后正常解完
- `unzip(zipFile, targetDir, StandardCharsets.UTF_8, 1, 1024 * 1024)` 抛 `IllegalStateException: zip条目数超过上限1，疑似压缩炸弹`
- `unzip(zipFile, targetDir, StandardCharsets.UTF_8, 10, 64)` 抛 `IllegalStateException`，消息是「累计解压字节超过上限64，疑似压缩炸弹，条目: 报表/明细.txt」
- `unzip(zipFile, targetDir, UTF_8, 0, 1024)` 抛 `IllegalArgumentException: 条目数上限必须大于0，当前为0`
- `unzip(zipFile, targetDir, UTF_8, 10, 0)` 抛 `IllegalArgumentException: 解压总大小上限必须大于0，当前为0`

---

🔢 **方法序号**：6

🎯 **方法用途**：
- 解压前先把包里的条目名按包内顺序清点出来，决定要不要解、解到哪
- 只看名字不动磁盘，验收外包、查重名这类场景不用先解压一遍

🧩 **方法定义**：`public static List<String> listEntries(Path zipFile)`

🗣️ **入参解释**：`public static List<String> listEntries(zip路径)`

📤 **返回值解释**：`List<String>`，包内条目名列表，保持包里的先后顺序

💡 **边界口径**：
- 目录条目以 `/` 结尾，和文件条目一起列出来
- 只做条目名清点，不校验条目名安全，`../` 这种穿越名照样原样列出来，要落地得用 `unzip`
- 空包返回空列表，不是 `null`
- 不是 zip 的文件在这里就被挡住，抛 `IllegalArgumentException`，不会像 `ZipInputStream` 那样当空包静默返回

🧪 **方法示例**：
- `listEntries(zipFile)` 拿到 [报表/, 报表/月度报表.txt, 说明.txt]，`报表/` 结尾带斜杠说明是目录条目
- `listEntries(穿越包)` 拿到 `[../逃出去.txt]`，清点阶段不拦，真正解压才会被拒
- `listEntries(空包)` 拿到 `[]`
- `listEntries(不是zip.txt)` 抛 `IllegalArgumentException`，消息是「不是合法的zip文件(缺少zip文件头)」再补上路径

---

🔢 **方法序号**：7

🎯 **方法用途**：
- 清点条目名时指定编码，旧 GBK 包也能看清里面到底叫什么
- 先用它确认编码，再把同一个编码传给 `unzip`，避免解出一目录乱码名

🧩 **方法定义**：`public static List<String> listEntries(Path zipFile, Charset charset)`

🗣️ **入参解释**：`public static List<String> listEntries(zip路径, 条目名编码)`

📤 **返回值解释**：`List<String>`，包内条目名列表，保持包里的先后顺序

💡 **边界口径**：
- 编码只作用在「没带 UTF-8 标记」的条目名上
- 解码失败抛 `IllegalArgumentException`，消息里说清用的是哪个编码
- 方法6 就是拿 `UTF_8` 调它
- 与 `unzip` 不同，这里不校验条目名安全，只做清点

🧪 **方法示例**：
- `listEntries(gbkZip, Charset.forName("GBK"))` 拿到 `[中文清单.txt]`
- `listEntries(gbkZip, StandardCharsets.UTF_8)` 抛 `IllegalArgumentException`，消息是「zip条目名无法按UTF-8解码，该包的条目名可能是别的编码（旧版Windows打的包传GBK）」
- `listEntries(zipFile, null)` 抛 `IllegalArgumentException: 字符集不能为null`

## 四、工具类源码（可直接复制）

📦 见评论区



把多个文件或目录递归打包成一个 zip、把 zip 安全解压到指定目录，中文条目名按 UTF-8 写、旧版 Windows 打的包可按 GBK 读，解压自带 Zip Slip 与压缩炸弹防护。

旧版Windows的ZIP包乱码？这个Java工具类支持按GBK读

编程语言

安全

Java ZIP工具类：支持多文件/目录递归打包、UTF-8/GBK中文编码兼容、ZipSlip与压缩炸弹防护。提供压缩级别控制、安全解压、条目名预览等功能。适用于JDK17+，处理旧版Windows中文包不乱码，自动拦截路径穿越与超限攻击，源码可直接复制使用。

文件系统

Windows

腾讯云双十一大促

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

旧版Windows的ZIP包乱码？这个Java工具类支持按GBK读-腾讯云开发者社区-腾讯云

旧版Windows的ZIP包乱码？这个Java工具类支持按GBK读

旧版Windows的ZIP包乱码？这个Java工具类支持按GBK读

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐