★ FEATURED ARTICLE 简介本资源面向在 Windows 平台使用 Qt 进行开发的程序员聚焦 zlib 与 Quazip 两个开源压缩库的编译产物与集成支持解决在 Visual Studio 2015 与 Qt 5.10 x86 环境下搭建压缩解压能力的实际问题。压缩包内共 35 个文件以 18 个头文件为主配合 4 个 lib 静态库、4 个 dll 动态库、4 个 exp 导出文件以及 pdb、ilk 等调试符号文件整体约 1.8MB覆盖编译、链接与调试各环节所需。资源按 3rd、zlib、quazip 等目录组织bin 与 include 分层清晰便于直接引入工程使用。已有 301 人学习下载适合需要快速获得可用库文件、省去自行编译配置成本的中初级 Qt 开发者参考。1. 从一次打包翻车说起quazip 和 zlib 到底该怎么配合上周帮一个做跨平台桌面工具的朋友排查问题他那边用 Qt 写了个日志归档模块打包成 zip 之后在 Windows 上能正常打开到了 Linux 上解压就报「invalid CEN header」文件列表读出来全是乱码。他一开始怀疑是文件系统编码问题折腾了半天最后发现根因是压缩库的调用姿势不对——他直接拿 zlib 裸压了数据流然后自己拼了个 zip 头文件名编码和中央目录偏移全对不上。这个场景其实特别典型很多人知道 zlib 是做压缩的也知道 quazip 是 Qt 生态里操作 zip 的封装但两者到底谁负责哪一层、什么时候该用谁脑子里是糊的。这份资源包围绕的就是 quazip 和 zlib 这套组合。zlib 是底层压缩算法库提供 deflate/inflate 能力处理的是字节流quazip 是建立在 zlib 之上的 Qt 封装负责 zip 归档格式的读写包括文件条目管理、目录结构、注释、以及和 QIODevice 的对接。简单说zlib 管「怎么把数据压小」quazip 管「怎么把一堆文件按 zip 规范装进一个包里」。如果你在做 Qt 项目需要程序内读写 zipquazip 基本是绕不开的选择如果你只是想把一段内存数据压一下再传走那 zlib 原生接口就够了没必要上 quazip。适合谁看正在用 Qt 做桌面或嵌入式工具、需要集成压缩归档功能的开发者已经用了 quazip 但被编码、路径、大文件、内存占用这些问题卡住的人以及想搞清楚 zlib 和 quazip 边界、避免重复造轮子的工程师。下面按「先搞懂分层 → 再动手编译集成 → 然后处理实际读写 → 最后避坑和进阶」的顺序展开中间会给可直接抄的代码和参数说明。2. 分层理解zlib 的 deflate 和 quazip 的归档模型2.1 zlib 到底提供了什么不提供什么zlib 的核心是一套无损压缩算法实现对外暴露的接口分两类一类是高层封装比如compress()和uncompress()适合一次性把整块内存压完另一类是底层流式接口围绕z_stream结构体配合deflate()和inflate()做分块处理。它处理的对象是连续的字节序列输出也是字节序列不涉及文件名、目录、时间戳这些概念。很多人第一次用 zlib 会误以为它能直接生成 zip 文件其实不是。zip 是一种归档格式除了压缩后的数据还要写本地文件头、中央目录、数据描述符等结构。zlib 只负责其中「压缩数据段」那一部分。你如果拿 zlib 压完直接存成.zip解压工具是认不出来的因为缺少归档元数据。这就是前面那个朋友翻车的根本原因——他把压缩和归档混为一谈了。zlib 的版本兼容性相对省心1.2.x 系列在各大平台都稳定1.3.x 开始对某些边界条件做了修正。常见做法是优先用系统包管理器装比如apt install zlib1g-dev或brew install zlib避免自己编译引入 ABI 差异。如果你在做静态链接注意 zlib 的许可证是 zlib License宽松商用没问题但要在文档里保留声明。2.2 quazip 在 zlib 之上补了哪几层quazip 的定位是「Qt 风格的 zip 读写库」。它把 zip 归档抽象成QuaZip对象把归档里的单个文件抽象成QuaZipFile并且让这些类继承或对接QIODevice这样就能和 Qt 的QDataStream、QTextStream无缝配合。它内部调用 zlib 完成实际的压缩和解压自己负责解析和生成 zip 结构。quazip 有几个版本分支需要注意。早期 0.x 版本 API 和现在差异较大0.7.x 之后逐渐稳定1.x 系列对 Qt5/Qt6 的支持更清晰。选型时先确认你的 Qt 版本Qt5 项目一般用 quazip 1.x 配 zlib 1.2.11 以上Qt6 项目需要 quazip 1.4 或更高因为 Qt6 移除了一些旧接口。如果你在 CMake 项目里集成quazip 提供了QuaZip::QuaZip目标用find_package(QuaZip)就能带进来比手动配 include 路径省事。一个容易忽略的点quazip 默认依赖 zlib 的哪些符号。它在编译时会探测 zlib 是否支持gzopen等 gz 系列接口如果系统 zlib 是精简版可能链接失败。常见做法是在 CMake 里显式指定ZLIB_ROOT或者用 quazip 自带的 bundled zlib 选项如果版本支持。我一般倾向于用系统 zlib减少一份代码副本但前提是确认版本和符号完整。2.3 什么时候只用 zlib什么时候必须上 quazip判断标准很简单看你要不要「多文件归档」。如果只是压缩一段配置文本、一张图片的字节流或者做网络传输前的数据压缩zlib 原生接口足够代码量小依赖少。如果你需要把多个文件打成一个包、保留目录结构、支持按条目读取、或者要和现有 zip 文件互操作那就必须用 quazip 这类归档库。还有一种中间情况你只需要读 zip 里的某一个文件不想引入完整 quazip。这种场景下minizip 或 libzip 也是选项但如果你项目已经是 Qt 技术栈quazip 的 QIODevice 集成优势明显读条目就像读普通文件一样。我一般会建议Qt 项目直接上 quazip非 Qt 项目再考虑 libzip 或 minizip避免为了一个功能引入整个 Qt 依赖。提示quazip 的 API 在不同大版本间有破坏性变更升级前先看QuaZipFile::open()的 mode 参数和QuaZip::setZipName()的替代关系别直接改版本号就编。3. 编译与集成把 quazip 和 zlib 接进你的构建系统3.1 用包管理器装 zlib再编 quazip最省事的路径是系统包管理器装 zlib然后源码编 quazip。以 Linux 为例先确认 zlib 开发包到位# Debian/Ubuntu 系 sudo apt update sudo apt install zlib1g-dev cmake qtbase5-dev # 确认 zlib 版本和头文件位置 dpkg -l | grep zlib1g-dev ls /usr/include/zlib.h这段命令做三件事装 zlib 开发头文件和静态库、装 CMake 和 Qt5 基础开发包、验证 zlib.h 存在。参数上zlib1g-dev是运行库对应的开发包别只装zlib1g否则编译时找不到头文件。Qt 这边如果用的是 Qt6把qtbase5-dev换成qt6-base-dev。接着拿 quazip 源码编译。假设你已经下载了 quazip 源码包进入目录后mkdir build cd build cmake .. -DCMAKE_BUILD_TYPERelease \ -DQUAZIP_QT_MAJOR_VERSION5 \ -DCMAKE_INSTALL_PREFIX/usr/local make -j$(nproc) sudo make installQUAZIP_QT_MAJOR_VERSION这个参数很关键quazip 用它决定链接 Qt5 还是 Qt6 的库。不指定的话CMake 可能自动探测到系统里多个 Qt 版本选错就编不过。CMAKE_INSTALL_PREFIX设成/usr/local是为了让后续find_package能找到如果你要装到自定义目录记得在项目里设CMAKE_PREFIX_PATH。3.2 CMake 项目里正确 find_package装完之后在你的项目CMakeLists.txt里这样接cmake_minimum_required(VERSION 3.16) project(MyZipTool LANGUAGES CXX) set(CMAKE_CXX_STANDARD 17) set(CMAKE_AUTOMOC ON) find_package(Qt5 REQUIRED COMPONENTS Core Gui) find_package(QuaZip REQUIRED) find_package(ZLIB REQUIRED) add_executable(myziptool main.cpp) target_link_libraries(myziptool PRIVATE Qt5::Core Qt5::Gui QuaZip::QuaZip ZLIB::ZLIB )这里QuaZip::QuaZip是 quazip 导出的 imported target它会自动带上 include 路径和链接依赖。ZLIB::ZLIB是 CMake 自带的 FindZLIB 模块提供的目标。两个都写上是因为 quazip 的 target 不一定传递 zlib 的链接信息显式写更稳。如果你遇到undefined reference to deflate这类错误八成就是 zlib 没链上。CMAKE_AUTOMOC ON必须开因为 quazip 的头文件里有 Q_OBJECT 宏需要 moc 处理。不开的话会在链接阶段报 vtable 缺失。这个坑我见过不止一次尤其是从纯 C 项目转过来的人容易忘。3.3 Windows 和 macOS 上的差异处理Windows 上用 vcpkg 或 MSYS2 会省很多事。vcpkg 方式vcpkg install quazip[core]:x64-windows vcpkg install zlib:x64-windows然后在 CMake 里通过 toolchain 文件引入。注意 vcpkg 的 quazip 端口可能默认用 Qt6如果你项目是 Qt5需要改 triplet 或手动指定 feature。MSYS2 下则是pacman -S mingw-w64-x86_64-quazip版本跟随仓库更新比较省心。macOS 上 Homebrew 有 quazip 公式但要注意它可能链接的是 Homebrew 自己的 Qt和你项目用的 Qt 版本不一致会导致符号冲突。常见做法是用brew install quazip之后在 CMake 里显式设Qt5_DIR指向你实际用的 Qt 安装路径避免混用。如果冲突严重就回到源码编译用-DCMAKE_PREFIX_PATH指定 Qt 路径。注意跨平台项目里zip 内文件名的编码处理在 Windows 和 Linux 上行为不同quazip 默认用 UTF-8 还是本地编码取决于编译选项后面避坑章节会细说。4. 实际读写用 QuaZip 和 QuaZipFile 完成归档操作4.1 创建一个 zip 并写入多个文件下面这段代码演示把两个文件写进 zip一个来自磁盘一个来自内存字符串#include QuaZip #include QuaZipFile #include QFile #include QDebug bool createArchive(const QString zipPath) { QuaZip zip(zipPath); // 以写入模式打开归档内部会创建 zip 结构 if (!zip.open(QuaZip::mdCreate)) { qWarning() 无法创建归档: zip.getZipError(); return false; } // 第一个条目从磁盘文件读入 QuaZipFile outFile(zip); if (!outFile.open(QIODevice::WriteOnly, QuaZipNewInfo(logs/app.log, /tmp/app.log))) { qWarning() 条目打开失败: outFile.getZipError(); return false; } QFile src(/tmp/app.log); if (src.open(QIODevice::ReadOnly)) { outFile.write(src.readAll()); src.close(); } outFile.close(); // 第二个条目直接写内存数据 QuaZipFile memFile(zip); QuaZipNewInfo info(config/settings.ini); // 设置压缩级别0 存储9 最大压缩 info.setCompressionMethod(QuaZip::cmDeflate); if (memFile.open(QIODevice::WriteOnly, info)) { memFile.write(QByteArray([core]\nthreads4\n)); memFile.close(); } zip.close(); return true; }逻辑上分几步先QuaZip::open(mdCreate)创建归档然后每个条目用QuaZipFile::open配合QuaZipNewInfo打开。QuaZipNewInfo的第一个参数是 zip 内路径第二个参数可选用来从磁盘文件继承时间戳和权限。setCompressionMethod可以选cmDeflate或cmStore后者不压缩只归档适合已经压过的数据。写完记得close()否则中央目录不完整解压工具会报错。参数说明QuaZip::mdCreate表示新建如果文件已存在会覆盖mdAdd是追加模式但 zip 格式追加支持有限一般不建议用。QuaZipNewInfo的路径分隔符统一用/即使在 Windows 上也别用反斜杠否则解压时目录结构会乱。4.2 读取 zip 内容并遍历条目读归档的典型流程是先拿条目列表再逐个打开void listAndRead(const QString zipPath) { QuaZip zip(zipPath); if (!zip.open(QuaZip::mdUnzip)) { qWarning() 打开失败: zip.getZipError(); return; } // 遍历所有条目 for (bool more zip.goToFirstFile(); more; more zip.goToNextFile()) { QuaZipFileInfo info; zip.getCurrentFileInfo(info); qDebug() 条目: info.name 压缩后: info.compressedSize 原始: info.uncompressedSize; // 只读文本类条目 if (info.name.endsWith(.ini) || info.name.endsWith(.log)) { QuaZipFile file(zip); if (file.open(QIODevice::ReadOnly)) { QByteArray data file.readAll(); qDebug() 内容前 100 字节: data.left(100); file.close(); } } } zip.close(); }goToFirstFile和goToNextFile是迭代器风格返回 bool 表示是否还有下一条。getCurrentFileInfo填充QuaZipFileInfo里面包含文件名、压缩前后大小、CRC、时间等。注意QuaZipFile打开时必须基于当前选中的条目所以顺序不能乱先goTo再open。如果只想读特定文件可以用zip.setCurrentFile(config/settings.ini)直接定位省去遍历。这个接口在条目多的时候能明显减少开销。读出来的数据是原始字节文本文件需要自己按编码转成 QStringquazip 不做编码转换。4.3 大文件分块读写与内存控制一次性readAll()在文件大时会吃内存。更稳的做法是分块bool extractLargeFile(QuaZip zip, const QString entryName, const QString outPath) { if (!zip.setCurrentFile(entryName)) { qWarning() 找不到条目: entryName; return false; } QuaZipFile inFile(zip); if (!inFile.open(QIODevice::ReadOnly)) { return false; } QFile out(outPath); if (!out.open(QIODevice::WriteOnly)) { return false; } const int bufSize 64 * 1024; // 64KB 块 QByteArray buf; while (!inFile.atEnd()) { buf inFile.read(bufSize); out.write(buf); } inFile.close(); out.close(); return true; }块大小设 64KB 是个折中太小系统调用多太大内存占用高。对于嵌入式场景可以降到 16KB。atEnd()在 QuaZipFile 上能正确判断解压流是否结束不用自己算大小。写磁盘时如果目标目录不存在需要提前QDir().mkpath()quazip 不会帮你建目录。提示解压时如果条目名包含../存在路径穿越风险生产代码里要校验条目名拒绝带上级目录的路径。5. 避坑与排查编码、路径、版本和内存的五个血泪经验5.1 中文文件名解压乱码现象在 Windows 上用资源管理器打开 zip中文文件名显示正常但在 Linux 上unzip -l看到乱码或者反过来。原因zip 格式对文件名编码没有强制规定Windows 常用本地代码页GBKLinux 常用 UTF-8。quazip 默认行为取决于编译时是否定义了QUAZIP_USE_QT_ZLIB等宏以及QuaZipNewInfo传入的字符串编码。解决写入时统一用 UTF-8并在QuaZipNewInfo构造前把 QString 转成 UTF-8 的 QByteArray 再传。读取时如果发现乱码尝试用QTextCodec::codecForName(GBK)转一遍。更彻底的做法是在 zip 条目里设置 UTF-8 标志位quazip 1.x 在QuaZipNewInfo里有对应选项具体看版本头文件。我一般会在项目里强制约定所有 zip 内路径用 UTF-8跨平台交换前先用工具验证一遍。5.2 路径分隔符和目录条目缺失现象解压后所有文件平铺在一个目录子目录结构没了。原因写入时用了反斜杠\作为分隔符或者只写了文件条目没写目录条目。zip 规范里目录条目以/结尾很多解压工具依赖这个来建目录。解决QuaZipNewInfo的路径一律用/比如logs/2024/app.log。如果目录层级多可以显式添加目录条目QuaZipNewInfo(logs/)但多数现代解压工具能根据文件路径自动建目录不强制。保险起见我在生成归档时会先写目录条目兼容性更好。5.3 链接时报 zlib 符号未定义现象编译通过链接阶段报undefined reference to deflateInit2_或inflate。原因quazip 的 CMake target 没有传递 zlib 依赖或者系统里装了多个 zlib比如 Anaconda 自带一个链接器找到了头文件但没找到对应库。解决在target_link_libraries里显式加ZLIB::ZLIB。如果还不行用ldd或otool -L看最终可执行文件链接的 zlib 路径确认不是指向了错误版本。Anaconda 环境下的常见做法是在 CMake 里设ZLIB_ROOT指向系统路径或者干脆在干净 shell 里编译。5.4 大文件压缩时内存暴涨现象压缩一个几百 MB 的文件进程内存占用到几个 GB。原因用了readAll()一次性读入或者 zlib 的压缩级别设太高9 级且块大小太大。zlib 在最高压缩级别会维护较大的滑动窗口和哈希表。解决分块读写压缩级别降到 6 左右性价比最高。如果确实需要高压缩比考虑用QuaZip::cmDeflate配合setCompressionLevel单独调而不是全局设 9。另外quazip 在写入时如果条目多中央目录会缓存在内存条目数上万时要注意可以分批归档。5.5 Qt6 下编译报 QIODevice 接口变更现象从 Qt5 升到 Qt6 后quazip 编译报open函数签名不匹配或者QIODevice::OpenMode相关错误。原因Qt6 调整了部分虚函数签名旧版 quazip 没适配。解决升级 quazip 到 1.4 以上并在 CMake 里设QUAZIP_QT_MAJOR_VERSION6。如果项目同时要兼容 Qt5 和 Qt6用条件编译区分或者维护两个构建配置。我一般会在 CI 里同时跑 Qt5 和 Qt6 两套构建尽早暴露这类问题。6. 进阶技巧用 QuaZip 做增量归档和完整性校验6.1 增量追加条目的可行做法zip 格式理论上支持追加但中央目录在文件末尾追加后需要重写中央目录。quazip 的mdAdd模式能打开已有归档并追加条目但要注意如果原归档有注释或数字签名追加后可能失效。实际做法是先用mdUnzip读出所有条目信息再用mdCreate新建一个归档把旧条目和新条目一起写进去。这样虽然多一次拷贝但结构干净兼容性最好。如果归档不大直接全量重写更省心。代码上就是遍历旧归档逐个QuaZipFile读出再写入新归档最后替换文件。注意在 Windows 上文件被占用时不能直接覆盖需要先写到临时文件再QFile::rename。6.2 校验 CRC 和大小确认归档没坏quazip 在读取时会自动校验 CRC如果数据损坏read()返回 -1 或getZipError()非零。可以主动做一轮校验bool verifyArchive(const QString zipPath) { QuaZip zip(zipPath); if (!zip.open(QuaZip::mdUnzip)) return false; for (bool more zip.goToFirstFile(); more; more zip.goToNextFile()) { QuaZipFile file(zip); if (!file.open(QIODevice::ReadOnly)) { qWarning() 打开失败: zip.getCurrentFileName(); return false; } // 读空数据触发 CRC 校验 while (!file.atEnd()) { file.read(8192); } if (file.getZipError() ! QuaZip::NoError) { qWarning() CRC 校验失败: zip.getCurrentFileName(); return false; } file.close(); } zip.close(); return true; }这段代码逐个条目读完数据触发 zlib 的 CRC 校验。getZipError()返回NoError表示该条目完整。对于大归档全量校验耗时可以只校验关键条目或者用QuaZipFileInfo里的 CRC 值和实际计算值对比但后者需要自己实现 CRC32。6.3 和外部工具互操作的验证习惯写完 zip 后别只用自己代码读一遍就完事。我一般会强制走一遍外部验证Linux 上用unzip -t测完整性Windows 上用 PowerShell 的Expand-Archive试解压macOS 上用ditto -x -k解。三个平台都过了才认为归档格式没问题。这个习惯帮我拦下过好几次编码和路径的坑。另外如果 zip 要发给别人建议在文件名里带上生成时间和版本号避免对方拿到旧包。归档内部可以放一个manifest.json记录条目清单和校验值方便排查。从那以后我每次集成 quazip 和 zlib都会先跑一遍跨平台解压验证再检查中文路径和大文件分块最后才提交。希望帮到你。本文还有配套的精品资源点击获取
阅读完成 · 觉得有帮助？
