minizip是zlib项目附带的轻量级c接口zip处理库，非c++标准库组件，因其纯c风格、无raii和手动资源管理而未被纳入标准库。
minizip 是什么，为什么不是标准库的一部分
C++ 标准库不提供 ZIP 文件处理能力，minizip 是 zlib 项目附带的一个轻量级 C 接口封装，用于读写 ZIP 归档。它不是 C++ 类，没有 RAII、异常或 STL 容器集成，纯 C 风格，靠手动管理 zipFile / unzFile 句柄。这意味着你得自己打开、检查返回值、显式关闭——漏掉 unzClose() 或 zipClose() 就可能泄露文件描述符或临时文件。
它适合嵌入式、跨平台 CLI 工具或对依赖极敏感的场景；但不适合需要流式解压、密码保护（原生不支持 AES）、或自动内存管理的项目。
如何编译并链接 minizip（以 CMake 为例）
minizip 不是独立库，而是 zlib 源码树下的子目录（contrib/minizip/）。直接用系统 zlib 的头文件和库通常会失败，因为多数发行版不打包 minizip 的 .c 文件。
正确做法是把 zlib 源码拉下来，启用 minizip 构建：
- 从 zlib.net 下载源码，解压后进入
contrib/minizip/ - 确保已安装 zlib 开发包（如 Ubuntu 上
sudo apt install zlib1g-dev） - 在项目中添加：
add_subdirectory(path/to/zlib/contrib/minizip) target_link_libraries(your_target minizip z)
- 包含头文件时用
#include "unzip.h"和#include "zip.h"，路径需确保可访问（建议用target_include_directories(... PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/zlib/contrib/minizip)）
常见错误：undefined reference to unzOpen —— 说明只链接了 z 库，没链接 minizip 静态库；unzip.h: No such file —— 头文件路径未加入 include search list。
用 unzip.h 解压单个文件到内存（非提取到磁盘）
unzOpen() 打开 ZIP 后，必须先调用 unzGoToFirstFile() 或 unzLocateFile() 定位目标项，再 unzOpenCurrentFile() 才能读取。跳过定位步骤会导致 unzOpenCurrentFile() == UNZ_END_OF_LIST_OF_FILE。
示例：读取 ZIP 中某个文本文件全部内容到 std::vector<uint8_t></uint8_t>：
unzFile uf = unzOpen("archive.zip");
if (!uf) return false;
if (unzLocateFile(uf, "config.json", 2) != UNZ_OK) {
unzClose(uf);
return false;
}
if (unzOpenCurrentFile(uf) != UNZ_OK) {
unzClose(uf);
return false;
}
std::vector<uint8_t> buf(4096);
std::vector<uint8_t> out;
int read;
while ((read = unzReadCurrentFile(uf, buf.data(), buf.size())) > 0) {
out.insert(out.end(), buf.begin(), buf.begin() + read);
}
unzCloseCurrentFile(uf); // 必须调用！否则下次无法操作
unzClose(uf);</uint8_t></uint8_t>
注意：unzReadCurrentFile() 返回的是实际字节数，可能小于请求长度；返回 0 表示 EOF；返回负数表示错误（如 CRC 校验失败）。不要假设一次读完。
用 zip.h 添加文件时如何避免中文路径乱码
minizip 原生使用 Latin-1 编码写入文件名，Windows 上 GBK、macOS/Linux 上 UTF-8 路径都会显示为乱码或无法识别。ZIP 规范本身不强制编码，但现代解压工具（如 Windows 资源管理器、7-Zip、macOS 归档实用工具）默认按 UTF-8 解析文件名字段 —— 前提是 ZIP 中设置了通用位标志 bit 11（UNZ_IFLAG_UTF8）。
但 minizip 的 zipOpenNewFileInZip3() 不暴露该标志控制入口。可行方案只有两个：
- 用
zipOpenNewFileInZip3()传入 UTF-8 编码的filename，并在调用前手动设置 ZIP 文件头的通用位（需修改 minizip 源码或 patchzip.c中zipWriteInFileInZip内部逻辑） - 改用更现代的替代品，如
libzip（支持zip_file_add()+zip_set_file_compression()+ 自动 UTF-8 处理）或 C++ 封装库miniz-cpp（非官方，但修复了编码问题）
硬编码转 GBK 或 Shift-JIS 是不可移植的，且会让 macOS/Linux 用户完全无法看到正确文件名。这个问题没有“开箱即用”的安全解法。
真正麻烦的地方不在 API 调用是否成功，而在于 ZIP 文件名编码、时间戳精度（tm_unz 只有秒级）、以及缺乏对 ZIP64 扩展的透明支持——这些细节一旦出错，生成的 ZIP 在某些系统上就打不开，但错误又不会在 zipClose() 时抛出。
C++免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 C++ 的入门与实战技巧！
