简介：这是一份专为Windows平台C++开发者准备的QuaZip预编译库资源，面向需要在Qt5项目中处理ZIP/RAR档案的程序员。QuaZip支持打开、创建、读取、更新和删除ZIP文件，并对RAR提供基本读取能力；包内已编译好静态.lib和动态.dll，免去自行构建的繁琐步骤，可直接在Visual Studio、Qt Creator等环境集成。压缩包共29个文件，含17个头文件、5个CMake配置、4个lib库、2个dll运行库及1个pc配置文件，整体仅427KB；文件按install目录组织，便于链接器与包含路径设置。目前已有595人学习下载，适合中高级C++开发者快速为项目补充压缩功能。通过lib与dll的组合，开发者既可静态链接生成独立可执行文件，也可动态加载控制运行时依赖；结合QuaZip提供的getFileInfoList、QuaZipFile等接口，能快速实现档案遍历、文件读取、添加与删除，并借助内置错误处理机制提升程序健壮性，显著降低编码与排错成本。 自己在Qt项目里集成压缩功能时，十有八九会遇到QuaZip这个名字。它是Qt环境下处理ZIP压缩包最顺手的C++库，底层封装了ZLib，接口完全贴合Qt的IO系统，读写ZIP就像操作QFile一样自然。不过QuaZip有个特点——官方基本不发布预编译的二进制包，而是让使用者自己动手编译集成。于是“QuaZip编译好的库lib、dll”就成了一个经久不衰的需求。
这篇文章就是要把整个编译和使用流程拆开揉碎，说清楚为什么需要编译、怎么用CMake生成对应版本的lib和dll、怎么在Qt工程里配置运行环境，还会把编译集成过程中常见的报错和排查经验一起倒出来。适合刚接触QuaZip、只想要一份能跑的Windows版lib/dll，或者被各种编译问题卡住的开发者参考。
1. QuaZip是什么，为什么需要自己动手编译
有些读者可能是临时拿别人的代码来做集成，也有不少人是刚从C#、Java转到Qt开发，对C++生态里的源码编译、链接、动态库这套流程还不熟。先花几百字把QuaZip的背景和定位说清楚。
1.1 核心功能与典型应用场景
QuaZip是一个基于Qt和ZLib的开源ZIP压缩解压库。它最大的特点是把ZIP文件抽象成类似于QFile的对象，开发者在Qt项目里压缩、解压、遍历ZIP条目时，不需要面对一堆C风格的ZLib接口，也不用自己操心内存分配和文件句柄管理，整体代码写起来非常顺手。
典型的应用场景包括：
- 桌面工具导出报表后打成ZIP包，比如将多个CSV、Excel、图片文件一起压缩归档。
- 程序更新包的解压模块，下载一个ZIP后直接解压到指定目录并覆盖旧文件。
- 工程类软件保存项目文件时，用一个
.zip格式封装QML资源、JSON配置和二进制数据。 - 支持密码解压的场景，QuaZip对ZIP标准加密有比较完整的支持。
相比Qt原生就带的QZipReader/QZipWriter（这类API在Qt官方一直没有公开稳定化），QuaZip的接口更全，社区也更活跃，所以很多商业项目会直接选QuaZip来做这块功能。
1.2 直接找现成lib、dll的坑
标题里最吸引人的是“编译好的库”几个字，我也曾经直接去GitHub的Release页面找打包好的二进制文件。结果是绝大多数官方发布版并不提供编译好的产物，第三方分享的DLL又常常因为Qt版本、编译器、位数不匹配导致程序运行时报“应用程序无法启动”或“无法定位程序输入点”。
举个例子：你用MSVC 2019 + Qt 5.15.2编译了调用程序，然后拿到一个用MinGW编译的quazip.dll，加载时往往直接失败。因为MSVC和MinGW生成的动态库对C++名称修饰规则、运行时库的处理完全不同，根本没法混用。
所以“拿到别人编译好的lib、dll”这件事，在自己本地上永远是短视方案。真正一劳永逸的办法是花十五分钟，自己动手把对应版本的QuaZip编译出来，一劳永逸地解决ABI匹配问题。
2. 编译前的环境准备
如果已经用上Qt 5.15或Qt 6.x，那么环境基本齐全。QuaZip本身没有多复杂的依赖，只要把编译器、CMake、Qt安装路径理清楚，编译过程可以做到非常顺滑。
2.1 选择Qt版本与编译器
QuaZip现在对Qt 5和Qt 6都支持，推荐直接使用CMake构建。这意味着只要你安装Qt时勾选了对应的编译套件（比如MSVC 2019/2022或MinGW），并且安装了CMake，环境就准备好了。
几个必须注意的匹配关系：
| 匹配项 | 说明 |
|---|---|
| Qt版本 | 必须与调用工程一致，比如调用方用Qt 5.15.2，QuaZip也必须是同版本编译 |
| 编译器 | MSVC和MinGW不能混用，Debug和Release也不能混用 |
| 位数 | x64和x86必须清楚区分，一个32位程序加载64位DLL必定失败 |
我自己的开发环境通常是“Qt 5.15.2 MSVC2019 64位”，所以下面的命令全部以这套环境为例。如果读者用的是MinGW，只需要把生成器参数从Visual Studio换成MinGW Makefiles，其他思路完全一致。
2.2 获取QuaZip源码与依赖关系
QuaZip的源码可以直接从GitHub获取，搜索QuaZip或者直接访问其仓库。下载后先看根目录的CMakeLists.txt，重点关注两个地方。
第一是ZLib依赖。QuaZip底层依赖ZLib，而Qt自带了ZLib动态库，比如Qt5.15.2/5.15.2/msvc2019_64/lib/zlib1.dll。理论上CMake配置时能自动找到Qt自带的ZLib，如果找不到，可以额外指定ZLib的路径。
第二是BZip2和AES相关选项。某些功能会用到libbz2或OpenSSL。如果不依赖这些高级功能，建议直接关闭，少一个依赖就少一个坑。比如把BUILD_WITH_BZIP2设为OFF，把BUILD_WITH_AES设为OFF，官方默认配置下这两项通常可以被正确探测到，但为了编译速度和不必要的系统依赖，我经常手动关闭。
3. 用CMake编译QuaZip的完整步骤
这一部分直接给可以照做的命令行操作。假设已经安装好Qt 5.15.2 MSVC2019 64位，Qt安装目录为C:/Qt/Qt5.15.2/5.15.2/msvc2019_64，QuaZip源码解压到D:/lib/quazip-1.4。
3.1 生成工程文件
在源码目录外新建一个build目录，然后执行CMake配置命令：
cd D:/lib mkdir quazip-build cd quazip-build cmake ../quazip-1.4 -G "Visual Studio 16 2019" -A x64 -DCMAKE_PREFIX_PATH=C:/Qt/Qt5.15.2/5.15.2/msvc2019_64 -DCMAKE_BUILD_TYPE=Release -DBUILD_WITH_BZIP2=OFF -DBUILD_WITH_AES=OFF有几点要说明：
-DCMAKE_PREFIX_PATH是给CMake找Qt库和头文件的路径。很多人卡在这一步，如果忘记指定，CMake会报“Could not find Qt modules”之类的错误。-G指定使用VS 2019的工程生成器。如果是VS 2022，改为Visual Studio 17 2022。-A x64表示生成64位库，如果需要32位，这里改成Win32，同时Qt路径换成对应的msvc2019目录。
配置完成后运行cmake --build . --config Release（或者打开生成的.sln在Visual Studio里选Release模式编译），大约一分钟后就能在build/release目录下看到quazip.dll和quazip.lib了。
3.2 编译并检查产物
编译完成后，检查三个目录：
- 头文件：源码根目录
quazip/下的.h文件。 - 动态库：
build/release/quazip.dll。 - 导入库：
build/release/quazip.lib。
这三个东西在调用工程里分别对应#include、运行时DLL、链接期LIB。
如果编译过程遇到静态库和动态库同时生成了，也不用奇怪。CMake默认会同时生成quazip.dll和quazip.lib，其中quazip.lib是动态库的导入库，不是静态库的直接产物，链接时用的是它，运行时需要的还是quazip.dll。
3.3 在Qt项目中使用编译好的库
拿到lib、dll和头文件后，叫停编译工作，接下来是工程集成。把以下内容写入Qt工程的.pro文件：
INCLUDEPATH += D:/lib/quazip-1.4/quazip LIBS += -LD:/lib/quazip-build/release -lquazip如果使用CMake构建Qt项目，则在CMakeLists.txt里：
include_directories(D:/lib/quazip-1.4/quazip) target_link_libraries(MyApp D:/lib/quazip-build/release/quazip.lib)代码里使用的时候，最简写法如下：
#include <JlCompress.h> QString zipPath = "D:/test.zip"; QString destDir = "D:/unzip"; JlCompress::extractDir(zipPath, destDir);这个JlCompress.h是QuaZip提供的高级工具封装，简单场景下压缩解压几行代码就能搞定。不过先别急着高兴，运行程序前还要把quazip.dll复制到exe同目录，或者加进系统PATH。开发调试时可以在Qt Creator的运行环境变量里直接把D:/lib/quazip-build/release加进去。
4. 我踩过的坑和排查方法
编译QuaZip整个过程并不难，但集成到真实项目时，各种玄学问题就会冒出来。下面这些是我自己在不同项目里反复踩过的坑，整理成速查列表。
4.1 DLL加载失败，程序启动即崩溃
最典型的错误是Qt5Core.dll找不到，或者quazip.dll加载失败。这类问题十有八九是运行时没有找到Qt自带的DLL。
排查思路：
- 用Dependency Walker或者Process Explorer查看exe加载的DLL列表，看是否所有依赖都在。
- 确认
quazip.dll和调用exe都使用同一个编译器与Qt版本构建。 - 如果程序用了release版Qt，而QuaZip却连了debug版，也会报错“无法定位程序输入点于quazip.dll”，必须严格区分Debug和Release。
另外要注意，Qt 5.15版本之前的程序，发布时还要把Qt5Core.dll、Qt5Gui.dll、Qt5Widgets.dll等一并带上。简单的做法是使用Qt自带的windeployqt.exe自动拷贝运行库。
关于DLL冲突，我见得最多的场景是项目目录里同时存在多个版本的quazip.dll，系统搜索路径时加载了旧版本，导致某些接口找不到。发布时，在exe同目录且只能有一个quazip.dll，这是铁律。
4.2 CMake找不到Qt模块或ZLib
执行CMake配置时如果提示找不到Qt5Core或Qt6Core，多半是CMAKE_PREFIX_PATH没指向Qt编译器目录。直接将-DCMAKE_PREFIX_PATH设置为Qt对应的库目录即可。
如果提示找不到ZLIB：
- 确认Qt安装目录的
lib下是否有zlib1.dll和zlib.lib。有些Qt安装选项不会附带zlib，可以通过Tools/QtCreator目录下查找，或者额外下载zlib源代码自己编译。 - 也可以开启CMake变量直接用系统安装的ZLib，比如指定
-DZLIB_INCLUDE_DIR和-DZLIB_LIBRARY。 - 或者最简单的方式，完全避开外部ZLib依赖，把CMake选项里
BUILD_SHARED_LIBS和ZLib相关的配置调成Qt内置版本。
还有一种情况是CMake配置时报找不到OpenSSL，是因为BUILD_WITH_AES默认开启导致。如果不需要带密码的高强度AES加密，直接-DBUILD_WITH_AES=OFF，立刻清爽。
4.3 头文件或宏定义不匹配
少部分使用QuaZip源码编译教程的同学，会在编译时碰到“无法打开包含文件‘zlib.h’”或“quazipnewinfo.h找不到”之类的问题。除了确认头文件路径齐全，还要注意宏定义这个隐蔽坑。
在MSVC环境下，如果定义了QUAZIP_STATIC，会让编译代码去找静态库的符号；如果在调用exe里动态链接却定义了该宏，链接时就会报大量无法解析的外部符号。所以：
- 动态链接：不要定义
QUAZIP_STATIC。 - 静态链接：在代码或
.pro中定义QUAZIP_STATIC，并链接quazip_static.lib或直接添加源码编译。
4.4 多文件编译与增量编译问题
题外话，很多人在编译器这里被“dll冲突”和“多文件编译”带偏，其实这和QuaZip本身关系不大。QuaZip是常规的C++库，在CMake或qmake工程中都能正常参与增量编译。如果在Visual Studio里修改头文件后出现“unreferenced label”之类的C语言编译错误，通常不是QuaZip导致的，而是代码里某些宏或函数没有正确声明。逐个排查前，先把QuaZip头文件单独放到一个简单测试工程里验证，确认库本身没问题，再去查业务代码。
5. 一些值得说的实操心得
每次折腾第三方库，最难的不是编译本身，而是各种环境下ABI问题的排查。这里分享一下我在多个项目里沉淀下来的经验。
5.1 一定要用脚本固化编译流程
我遇到过一个很现实的问题：几个月后QuaZip升级，或者同事换了一台电脑，要重新生成一份lib和dll。如果每次都手敲CMake命令，很容易因为路径、参数不一致浪费半天时间。
我的做法是写一个简单的构建脚本，把CMake配置、编译、拷贝头文件和DLL到项目第三库目录这几步全部串起来：
@echo off set QT_PREFIX=C:/Qt/Qt5.15.2/5.15.2/msvc2019_64 set QUAZIP_SRC=D:/lib/quazip-1.4 set BUILD_DIR=D:/lib/quazip-build cmake %QUAZIP_SRC% -B %BUILD_DIR% -G "Visual Studio 16 2019" -A x64 -DCMAKE_PREFIX_PATH=%QT_PREFIX% -DBUILD_WITH_BZIP2=OFF -DBUILD_WITH_AES=OFF cmake --build %BUILD_DIR% --config Release这样无论什么时候换机器，双击脚本就能把依赖库准备好，也避免了手动拷贝漏文件的问题。
5.2 调试版本与发布版本用不同目录
如果经常要调试程序，务必分别编译一份Release和一份Debug的quazip.dll。混用版本时，程序会“偶然”跑起来，但一到解压大文件或者频繁压缩时，就会出现内存错误，最难排查。
平时重载提示“zlib1.dll 缺失”，或者其它模块悄悄加载了不同版本的zlib，都可能引发运行时崩溃。所以我在最终发布目录里，除了自己程序的exe和Qt动态库，只会保留一份明确的zlib1.dll，并确认版本来源。
5.3 熟悉C++库集成本质，未来事半功倍
QuaZip只是C++生态里无数需要手动编译的库的一个缩影。只要掌握“CMake + Qt环境 + DLL路径”这一套流程，以后遇到QScintilla、QCustomPlot、libcurl、Darknet这些需要编译的第三方库，都能举一反三。
当然，如果实在不想折腾编译，也可以考虑直接用Qt内置的方案，或者把压缩解压功能交给7zip的独立命令行程序，用QProcess调子进程，这种方式也能满足不少场景，但代码优雅性和实时进度控制就差了。
我在实际项目里还是更倾向把QuaZip编译好之后放进统一的三方库目录，之后所有涉及ZIP操作的功能都通过这个稳定版本进行开发。踩过几次坑之后，总结下来就是：认准Qt版本、认准编译器、严格区分Release和Debug，QuaZip不会再给人添乱。
本文还有配套的精品资源，点击获取
