搞C桌面开发的人基本都会碰上这个需求程序跑完要导出一份Excel给客户。QtXlsx这个库我最早是在一个报表项目里接触到的当时Qt本身没有官方的Excel读写模块团队里有人建议用CSV糊弄过去但客户明确要求多Sheet、合并单元格、字体颜色CSV根本扛不住。后来换到QtXlsx问题直接解决。它不依赖Office组件、纯C实现、跨平台能写能读.xlsx支持样式、公式、多工作表和图片算是Qt生态里最实用的Excel处理方案之一。这篇文章就是从零开始用 Qt 5.15 VS2019 MSVC2019 环境把QtXlsx源码编译成库再集成进自己的工程最后写出一个能读写Excel的完整Demo。整个过程我会把为什么这么做、每一步背后的逻辑、以及我踩过的坑都摊开讲。正在做桌面报表导出、或者刚接手Qt项目想快速落地的同学可以直接照这个流程走一遍。1. 项目概述为什么Qt程序读写Excel这么麻烦1.1 需求场景与痛点拆解我先梳理一下日常开发里“Qt要碰Excel”的场景。最常见的是两类一是数据导出程序计算完一堆结果需要按表格形式交给业务人员比如财务报表、设备清单、生产记录二是数据导入用户给一个Excel模板程序要读进来做批量处理比如批量导入人员信息、商品数据。这两类需求的共同特点是对格式有要求对数据量有一定容忍度而且程序跑在Windows桌面环境用户未必安装了Office。这里有个核心矛盾Qt官方并没有提供Excel读写模块。你翻遍Qt帮助文档也找不到一个叫QExcel的东西。早些年有人用QAxObject调用COM接口但那只能在Windows上用而且必须装Office或者WPS还有人绕道CSVExcel能打开CSV但样式、公式、多Sheet全部做不了遇到客户要求“字体加粗、单元格合并、列宽调整”就只能回到谈判桌。所以在项目里一个纯C、不依赖外部组件的Excel库就成了刚需这也是QtXlsx被很多桌面团队选中的原因。1.2 QtXlsx到底是什么能干什么QtXlsx是一个基于Qt开发的第三方库专门用于读写Office Open XML格式的Excel文件也就是我们常说的.xlsx。它不是一个官方产品而是社区里某个开发者发起、后来被放到公共代码托管平台维护的开源项目项目发展到现在已经积累了大量用户。核心能力可以概括成这么几块写入从零创建一个xlsx文件往指定单元格写入字符串、数字、日期、公式、布尔值还能合并单元格、设置列宽行高、加边框、设字体和颜色。读取加载现有xlsx遍历所有Sheet的所有单元格拿到单元格的值、格式、公式等信息。高级操作多Sheet管理、单元格批注、图片插入、条件格式、冻结窗格、打印设置等。依赖简单只依赖QtCore和QtGui不需要Office、不需要COM组件、不需要数据库驱动。有一点要提前说清楚它不支持旧版.xls格式不支持带宏的.xlsm对图表只支持简单的插入和读取复杂图表会丢失。如果客户拿给你的是老古董.xls文件先让他另存为.xlsx再处理。另外对于几十万行级别的超大ExcelQtXlsx也能处理但内存占用会比较高因为它在保存时会把整个文档结构放在内存里。中小规模数据完全够用这也是我实际项目里的主力场景。2. 方案选型与核心原理为什么选QtXlsx它是怎么工作的2.1 常见Excel读写方案横向对比我在不同项目里分别用过CSV、COM组件、ODBC和QtXlsx把这几种方案的优劣列成一张表大家可以直接对照着选型方案优点缺点适合场景CSV简单、Qt原生就能写无样式、无多Sheet、编码易乱、公式不支持临时导出、数据量小且格式要求低COM/QAxObject格式支持最全仅Windows、必须装Office/WPS、启动慢、易闪崩Windows内网环境、对样式要求极高ODBC/ADO能直接操作Excel依赖驱动、配置繁琐、类型转换问题多把Excel当数据库做条件查询直接操作XML不依赖第三方库需要理解xlsx内部结构、开发和Debug成本极高好奇心项目、格式极简单的特殊需求QtXlsx纯C、跨平台、样式齐全、维护简单不维护旧版xls、基础功能够用但高级图表有限Qt桌面软件读写xlsx的标准选择从表格能看出来QtXlsx在“跨平台样式支持开发成本”这三者之间取了一个很好的平衡。QAxObject功能确实最强但它把程序绑死在Windows和Office上客户机器一旦没装Office或者用的是精简版WPS程序就会在创建COM对象时直接卡死。而QtXlsx靠的是内置的打包和XML生成逻辑跟系统里装没装Excel毫无关系这在实际交付中是一个巨大的稳定性优势。2.2 QtXlsx的内部机制xlsx文件本质就是zipxml不懂原理直接配置库遇到问题往往一头雾水。我先花点篇幅讲明白QtXlsx是怎么工作的。一个.xlsx文件实际上是一个zip压缩包里面按照Open XML规范存放了大量XML文件。核心组成部分包括workbook.xml记录工作簿信息、sheet1.xml记录单元格数据和行列信息、sharedStrings.xml记录共享字符串、styles.xml记录样式定义。Excel打开xlsx时就是解压解析这些XML把它们渲染成表格界面。QtXlsx做的事情本质上就是替你生成这一整套符合规范的XML然后打包成zip再加上正确的文件扩展名。反过来读取时它解压xlsx文件解析各XML节点还原成Document对象你用API拿到的是结构化数据。理解这一点后很多行为就能解释了为什么它不能处理xls因为xls是二进制格式和xlsx完全不同为什么它不触发宏因为带宏的xlsm在XML结构里多了宏存储部分而QtXlsx没有实现为什么它支持样式却有些Excel高级功能缺失因为那些功能在XML规范里的对应节点它没有全部实现。2.3 为什么需要自己编译源码QtXlsx跟普通第三方库不太一样它没有给你分发现成的二进制文件。代码托管平台上只有源码官方也没有维护一个“下载即用”的预编译包。这意味着你要在你自己的Qt环境里用你手头的编译器和Qt版本把它从源码编成库文件。为什么非要自己编C库和目标程序之间存在严格的ABI兼容性问题。MSVC2019编译的库不能直接丢给MinGW项目用Qt 5.12下编出来的库放在Qt 5.15项目里也可能因为Qt版本接口差异导致链接错误。Qt自身是由qmake或CMake管理的QtXlsx也是Qt工程结构最稳妥的办法就是拿到源码后在你的目标环境中重新构建一次确保编译工具链、Qt版本、debug/release模式全部一致。这个过程听起来麻烦实际走一遍也就几分钟。还有一点QtXlsx已经很久没有大版本更新了。某些分支在Qt 5.15上编译会有小问题所以我一般会建议直接拉取代码托管平台上的最新提交或者用适配性较好的releases版本而不是随便找个旧版教程里的历史版本。这个细节很多人第一次编译失败就栽在这里。3. 环境准备与源码构建从零开始把库编出来3.1 环境清单与验证先说清楚我这篇文章针对的环境Windows 10 或 Windows 11、已安装 VS2019、已安装 Qt 5.15.2 并勾选了“MSVC 2019 64-bit”组件。如果你用的是MinGW版本Qt流程类似只是make工具从nmake换成mingw32-make链接库的后缀和名称略有不同。构建前建议先做好三件验证避免后面报错时搞不清是环境问题还是源码问题确认qmake可用。在命令行执行qmake -v能显示Qt版本信息就算通过。确认VS编译环境可用。我建议直接打开“x64 Native Tools Command Prompt for VS 2019”这个命令行窗口里已经配置好了cl.exe、nmake.exe、link.exe等工具。确认Qt的bin目录被加到了PATH里。如果你用VS命令行里面默认没有qmake需要手动执行一次类似set PATHC:\Qt\5.15.2\msvc2019_64\bin;%PATH%的命令把Qt工具链接进来。很多人喜欢直接双击“Qt 5.15.2 (MSVC 2019 64-bit)”快捷方式在这个Qt自带的命令行里执行构建。如果发现nmake命令不存在就说明这个窗口没有联动VS环境需要先执行vcvars64.bat。我实测下来最省心的是打开VS2019的开发者命令行再手动引入Qt的bin路径两边环境都齐了。3.2 获取QtXlsx源码的正确姿势在代码托管平台上搜索QtXlsx你会看到源码仓库。获取源码有两个方式一是用git clone直接把仓库拉到本地二是下载zip包。我推荐clone因为后续想切换分支或者拉更新比较方便。需要注意的一个坑QtXlsx的仓库里有些历史commit是针对老版本Qt设计的直接下载默认分支可能编译报错。我的建议是优先看releases版本选一个标注兼容Qt5的release比如比较常见的1.5.0版本。不同分支在src/xlsx目录下的pro文件会有细节差异如果你用的分支版本在编译时报“Unknown module(s) in QT”这种错误多半是pro文件引用了当前Qt环境里没有的模块把多余的模块项删掉即可。这些都是可以现场处理的。源码拿到后把它放到一个不含空格和中文的路径下比如D:\third_party\QtXlsx。这一步很有必要qmake和nmake对带空格的路径处理虽然不是完全不行但出错时排查成本很高尤其后面做自动化脚本时路径里的空格就是定时炸弹。3.3 使用命令行构建的完整过程进入源码目录后不要直接在源码根目录编译我习惯新建一个build目录把编译产物和源码隔离开。以MSVC2019工具链为例完整命令如下cd /d D:\third_party\QtXlsx mkdir build_qt5 cd build_qt5 qmake ..\qtxlsx.pro nmake第一遍执行qmake时会出现一串配置输出重点看两处One是项目类型是“lib”而不是“app”Two是Qt版本是不是你预期的5.15.x。确认无误后nmake就开始编译了整个过程会输出大量编译日志等它跑完没有出现error就算成功。这里要解释一下为什么用的是nmake而不是直接拿VS的“生成解决方案”。QtXlsx的工程是qmake体系用VS图形界面打开会提示安装Qt插件而且VS自带的编译器环境在图形界面上处理pro文件效率并不高。命令行方式反而更透明出错了你能看到是哪个文件、哪一行报错定位更直接。如果你机器上装了Perl比如Strawberry Perl构建会更顺滑。原因是qmake在生成某些中间文件时会调用Perl脚本不过实际操作中大多数时候不装Perl也能编过。遇到下面这类报错再补装也不迟perl 不是内部或外部命令也不是可运行的程序或批处理文件3.4 构建产物说明与放置策略nmake编译完成后在build目录下会生成对应模块的库文件。Release模式下通常能看到Qt5Xlsx.lib和Qt5Xlsx.dllDebug模式下可能是Qt5Xlsxd.lib和Qt5Xlsxd.dll具体命名取决于构建配置。同时源码目录里的头文件会被整理到include目录下比如xlsxdocument.h、xlsxformat.h、xlsxcell.h、xlsxcellrange.h这些核心头文件。这里有一个很容易忽略的坑如果直接执行nmake install库文件会被安装到Qt安装目录的lib和include下这样做确实省事但我不推荐。原因有两个第一你可能会在无管理员权限的环境下工作install会失败第二把第三方库混进Qt标准目录会让项目依赖变得不清晰以后换台电脑部署项目时说不清QtXlsx是从哪来的。我建议的做法是建一个专门的第三方库目录比如D:\third_party\QtXlsx\output手动把lib文件、dll文件和头文件复制过去然后在自己的工程里通过pro文件的变量引用这个目录。这样整个项目的依赖边界非常明确打包拷给别人时也知道要带上哪些东西。4. VS2019Qt5.15工程集成把库接进你的项目4.1 创建项目和pro文件配置在VS2019里使用Qt需要先安装“Qt Visual Studio Tools”插件这个插件大家应该都熟悉。装好后新建项目时选择“Qt Widgets Application”或“Qt Console Application”根据自己的需求选。这里我要强调一个思路即便你在用VS的图形界面写代码Qt项目的构建配置依然由pro文件主导。不要尝试去手动修改VS的附加包含目录和附加库目录那样做不仅繁琐还很容易出现“VS能编译过但qmake一跑就挂”的诡异状态。Qt插件的设计模式就是你在pro文件里写规则VS插件负责调用qmake生成对应的构建方案。项目创建完成后打开pro文件内容大致是这个样子QT core gui greaterThan(QT_MAJOR_VERSION, 4): QT widgets TARGET ExcelDemo TEMPLATE app CONFIG c11 SOURCES main.cpp \ mainwindow.cpp HEADERS mainwindow.h4.2 include qtxlsx.pri 的细节和原理QtXlsx源码根目录下有一个qtxlsx.pri文件我的建议是直接用include命令把它引入到你的pro文件里而不是自己去翻头文件路径和库文件路径。原因很简单qtxlsx.pri内部已经帮我们处理好了所有细节包括把src/xlsx目录加入头文件搜索路径、自动链接QtXlsx模块、根据Debug和Release配置选择对应库文件名。具体写法是这样include (D:/third_party/QtXlsx/qtxlsx.pri)注意两点。一是路径里的分隔符建议用正斜杠/Windows下的反斜杠\在某些qmake解析情况下会出现转义问题。二是如果路径中包含空格请务必用引号把路径包起来或者干脆像前面说的把源码放在无空格路径下。include了pri之后你的pro文件并不会发生“自动安装库”之类的神奇效果它的本质是让qmake在解析工程时把qtxlsx.pri里的配置文本直接展开进当前工程配置。这样项目在编译时就能找到QtXlsx的头文件链接时也能正确找到生成的库文件。很多人说“include了pri但还是找不到头文件”大概率是include路径写错了或者生成VS工程后没有触发qmake重新解析。4.3 最低限度验证编译集成完成后先写一个最简单的main函数确保库能正确编译链接#include QCoreApplication #include xlsxdocument.h int main(int argc, char *argv[]) { QCoreApplication a(argc, argv); QXlsx::Document xlsx; xlsx.write(A1, Hello QtXlsx); xlsx.save(test.xlsx); return a.exec(); }在VS里直接构建运行如果一切顺利工作目录下会出现一个test.xlsx文件用Excel或者WPS打开能看到“Hello QtXlsx”。第一次跑通这一步整个配置工作就算完成了百分之八十。如果这一步报错多数问题集中在找不到头文件或者链接失败这类问题我在本文第6章会集中排查。5. 读写Excel的核心代码边写边讲5.1 写入Demo创建、取值、样式、合并当你把环境配置好之后代码层面的东西就变得很轻松了。我直接给出一个覆盖日常高频写入场景的Demo包含字符串、数字、公式、日期、样式和合并单元格#include QCoreApplication #include QDate #include xlsxdocument.h #include xlsxformat.h #include xlsxcellrange.h using namespace QXlsx; void writeExcelDemo() { Document xlsx; // 基础单元格写入 xlsx.write(A1, 项目); xlsx.write(B1, 数值); xlsx.write(A2, CPU使用率); xlsx.write(B2, 78.5); xlsx.write(A3, 内存使用量); xlsx.write(B3, 4096); // 写入公式 xlsx.write(B4, SUM(B2:B3)); // 写入日期QtXlsx会自动转为Excel日期类型 xlsx.write(C1, QDate::currentDate()); // 创建一个格式对象 Format titleFormat; titleFormat.setFontSize(12); titleFormat.setFontBold(true); titleFormat.setFontColor(QColor(0, 0, 255)); titleFormat.setHorizontalAlignment(Format::AlignHCenter); titleFormat.setBorderStyle(Format::BorderThin); // 带格式写入 xlsx.write(A1, 项目, titleFormat); xlsx.write(B1, 数值, titleFormat); // 合并单元格 xlsx.mergeCells(A5:C5); xlsx.write(A5, 汇总信息, titleFormat); // 设置列宽行高 xlsx.setColumnWidth(1, 20); xlsx.setColumnWidth(2, 15); xlsx.setRowHeight(1, 20); bool ok xlsx.save(demo_write.xlsx); if (!ok) { qWarning() 保存失败; } }逐段解释一下。write这个函数是重载最多的API第一个参数可以用“A1”这种单元格坐标也可以用行列数字write(row, col, value)两种写法人人都要用到。写公式时直接传字符串“SUM(...)”QtXlsx会识别成公式而不是普通文本这个能力在处理统计报表时非常有用你不用自己在C里算好结果把公式交给Excel去算就行。Format对象是QtXlsx的样式核心所有字体、对齐、边框、填充色都靠它设置。这里我特别想提醒一下合并单元格本身不会自动写入内容合并之后你还需要在合并区域的左上角单元格写入数据否则Excel里看到的是一片空白很多初学者刚接触时容易在这步踩坑。5.2 读取Demo加载、遍历、读取具体单元格读取比写入稍微绕一点因为你要面对一个未知结构的文件。最稳妥的方式是先加载文件再通过dimension()拿到当前工作表的数据范围然后逐行逐列读取。示例代码如下#include QCoreApplication #include QVariant #include xlsxdocument.h using namespace QXlsx; void readExcelDemo(const QString filePath) { Document xlsx; bool ok xlsx.load(filePath); if (!ok) { qWarning() 加载失败请检查文件路径; return; } // dimension() 返回当前工作表中包含数据的最小范围 CellRange range xlsx.dimension(); int rowCount range.rowCount(); int colCount range.columnCount(); qDebug() 总行数: rowCount 总列数: colCount; // 遍历所有单元格 for (int row 1; row rowCount; row) { for (int col 1; col colCount; col) { QVariant value xlsx.read(row, col); if (value.isValid()) { qDebug() QString((%1,%2)).arg(row).arg(col) value.toString(); } } } }核心思路是先load后通过read(row, col)按坐标取值。read返回的是QVariant遇到数字、日期、字符串、布尔值都会自动转换成对应类型你可以用toString()、toInt()、toDouble()等方法拿到底层值。还有一种进阶读取方式用cellAt(row, col)拿到Cell*指针然后通过cell-value()读取值同时还能访问cell-format()、cell-dateTime()等元信息。如果你需要读取单元格的样式、判断是否带格式就必须走cellAt这条路子read拿不到这些细节信息。我平时遇到“公式单元格读出为空”“日期格式读出来是序列号”这类问题通常都是因为只用了read没有深入cellAt去排查。5.3 高频功能补充多Sheet、格式、日期与公式实际项目里很少只操作默认Sheet。QtXlsx的多Sheet操作API不多但足够用。我给你列一个高频场景组合Document xlsx; // 新增Sheet并切换到它 Worksheet *sheet1 xlsx.addSheet(第一页); Worksheet *sheet2 xlsx.addSheet(第二页); // 在指定Sheet上写入 xlsx.selectSheet(第一页); xlsx.write(A1, 第一页数据); xlsx.selectSheet(第二页); xlsx.write(A1, 第二页数据); // 获取当前Sheet名 QString currentSheet xlsx.currentSheetName();需要注意selectSheet之后写入操作发生在当前Sheet上如果你写完一个Sheet忘了切回来下一个写入会跑到别的Sheet里这种bug属于逻辑错误编译器和运行时都不会报错只能在自测时发现。我自己的习惯是每个Sheet的写入块开始前都显式调用一次selectSheet哪怕当前就是那个Sheet。日期处理是另一个容易踩坑的地方。Excel内部日期其实是按“从1900年1月1日起的天数”存储的如果你写QDate对象QtXlsx内部会帮你转换成序列号再配置好单元格格式。但如果你读到的是一个数字序列号想还原成QDate需要自己调用转换方法。我建议写日期时尽量用QDate或QDateTime对象而不是直接写字符串“2024-01-01”那样写进Excel的只是个文本后续做日期筛选、排序会很麻烦。关于格式再补充一句Format对象可以复用别在一个循环里反复创建同类Format。比如生成一份报表要给所有表头行设置相同的底纹和字体就只创建一次Format对象然后循环写入时传同一个对象就可以。这样既省资源代码也更清晰。5.4 写代码时的三个小习惯结合我自己的开发经验总结三个能显著减少返工的小习惯。第一个习惯在save之前先确认目标目录存在且可写。QtXlsx在保存时不会自动创建目录如果你指定的路径是一个不存在的目录保存会静静失败不抛异常你连错误提示都看不到。所以开发阶段我会写一个封装函数保存前先检查目录是否存在。第二个习惯大批量写入时把数据先组织好再一次性写入避免在业务逻辑里穿插大量保存操作。Document对象会把所有数据缓存在内存里保存动作在最后一刻执行频繁保存不仅拖慢速度还可能在中间保存失败时给你留下一个残缺文件。第三个习惯读取时尽量使用const限制操作范围只读文件时不需要往Document里写数据。QtXlsx加载文件后如果不小心调用了write它会在内存里修改文档接下来再保存就会覆盖原文件。对于只读场景我在打开文件后严格避免任何write操作这个习惯帮我避开过好几次事故。6. 常见问题与排查实录这些坑我基本都踩过6.1 编译期问题对照表这部分是全文最有价值的干货。我自己在不同机器上重复配置了很多次QtXlsx遇到的编译问题翻来覆去就那几类整理成一张速查表错误现象可能原因解决方案Cannot open include file: xlsxdocument.h: No such file or directorypro文件没有正确include qtxlsx.pri或者include路径写错检查include路径是否存在确保使用正斜杠更新VS工程后重新qmakeLNK2019: unresolved external symbol QXlsx::Document::write 等大量链接错误没有链接QtXlsx库或者Debug/Release模式下库文件不匹配确认qtxlsx.pri被加载按构建配置重新编译库确认nmake时生成的是对应模式Unknown module(s) in QT: xxx源码pro文件引用了当前Qt环境没有的模块找到源码下的qtxlsx.pro和src/xlsx/xlsx.pro删掉多余模块项nmake 不是内部或外部命令没有在VS环境中执行构建命令打开“x64 Native Tools Command Prompt for VS 2019”再引入Qt的bin路径error: C2039: xxx: 不是xxx的成员Qt版本接口差异源码某个API在新版Qt里改名或删除按版本文档适配源码或者改用适配Qt 5.15的release分支qmake: could not exec g误用了MinGW的qmake确认当前PATH中qmake来自Qt 5.15.2 msvc2019_64目录链接错误LNK2019是我见过最多的。出现这个错误的同学十个里有八个是include了pri但没让VS重新解析工程另一个是Debug工程链接了Release库。解决办法很简单在VS里右键项目选择“Qt”菜单执行一下“Reset Project”或者在项目属性里手动触发qmake重新生成让pri里的链接配置真正生效。6.2 运行期问题与排查思路编译过了运行时又是一片新天地。先说最经典的“生成的xlsx文件打开提示损坏”。这种问题我在早年间遇到时百思不得其解后来定位到两个原因。一个原因是保存路径没写对程序把内容写到了一个不存在的目录QtXlsx保存失败后留下一个0字节或者残缺文件Excel打开自然报损坏。另一个原因是程序正在结束阶段强制杀进程导致文档没有完整flush到磁盘。排查方法很简单用记事本打开生成的xlsx文件看最前面的字符正常情况会看到PK开头的zip文件头如果是一堆乱码或者文件大小为0基本可以判定是保存环节出了问题。还有一个常见的运行期问题是“读取Excel时数据为空”。这不一定是你代码写错了很可能是原文件里有合并单元格。合并单元格的区域中只有左上角的单元格有值其他单元格在XML里根本没有显式数据。遍历读取时这些位置返回的QVariant是无效的显示出来自然就是空。这个不是Bug是Excel数据模型本身的特性遇到时要有所预期。6.3 中文字符与编码问题中文乱码是Qt中文开发者绕不开的话题。QtXlsx本身对中文的支持是没问题的它内部处理xlsx里的sharedStrings.xml时用的是标准的UTF-8编码。真正的问题往往出在你的源码文件编码和处理字符串的方式上。最典型的一个坑是在VS2019里如果源文件保存为GBK编码然后直接写xlsx.write(A1, 中文内容)QtXlsx拿到的可能是GBK字节被误解后的乱码。解决办法有三个方向在源文件头部加上#pragma execution_character_set(utf-8)这会告诉MSVC编译器把窄字符字符串字面量按UTF-8处理。在pro文件里配置CONFIG utf8_source让qmake和MSVC使用UTF-8解析源文件。统一使用QStringLiteral或者QString::fromUtf8来构造中文内容。我最推荐的是第三种因为它不依赖编译器参数也不会因为某个文件被不同编辑器改过编码而失效。比如写中文时用QString::fromUtf8(u8中文标题)明确告诉程序这串字节是UTF-8编码Qt内部转成QString后无论如何都不会乱。另一个编码细节如果你读取的xlsx文件原本是在WPS环境下创建的sharedStrings.xml里的字符串可能带有CRLF或者特殊字符QtXlsx会原样读出不需要你额外处理。倒是控制台输出的中文乱码是另一个问题那往往是Windows控制台代码页和UTF-8不匹配造成的跟文件数据本身没关系别被误导。6.4 发布与部署要注意的事程序在自己机器上跑通只是第一步交付给用户时还会遇到“DLL缺失”问题。QtXlsx的库文件不是Qt自带的模块windeployqt工具并不会主动把它收集到发布目录里。你需要手动把编译好的Qt5Xlsx.dll复制到exe所在目录或者通过pro文件的后处理命令自动完成。我推荐在pro文件里加一段自动复制命令省得每次发布都手动拷贝CONFIG(release, debug|release) { QMAKE_POST_LINK $$quote(cmd /c copy /Y D:\\third_party\\QtXlsx\\output\\release\\Qt5Xlsx.dll $$shell_path($$OUT_PWD/..)) }这段命令在Release构建完成后自动把Qt5Xlsx.dll复制到构建输出目录配合windeployqt一起使用发布流程就全自动了。如果不想改pro文件用CMake项目的同学也可以在构建脚本里写个copy_if_different命令原理一样。发布时还要留意一件事QtXlsx的dll本身会依赖对应的Qt运行库。如果你的程序是32位或64位对应的Qt5Xlsx.dll也得是同一架构混合架构组合会在程序启动时报“应用程序无法正常启动0xc000007b”排查思路就是检查所有dll的架构是否一致。7. 最后再补充几点个人经验聊到这里配置和代码都已经讲完了。再分享一点我对QtXlsx这个库的整体使用感受。做Qt桌面开发这么多年我用过的Excel方案不少但最终稳定下来的还是QtXlsx。它的学习曲线不算陡核心API拢共就那么几个类只要理解了Document、Format、CellRange这三个核心概念基本就能覆盖项目里九成以上的需求。虽然这个库没有商业产品那么完善的官方文档但它的源码结构清晰遇到不懂的API直接去读源码就行源代码也不算太大花一个下午通读核心部分心里就有底了。如果让我给后来者一个建议那就是不要一上来就追求复杂功能先把“创建文件、写几个单元格、保存成功”这条最简路径跑通然后再逐步叠加多Sheet、样式、公式这些需求。很多配置问题的根源在于项目和库的构建环境没对齐和你写的业务代码关系不大。环境一旦对齐后面就很顺了。还有一点是代码分层。我现在的项目里所有关于Excel读写的代码都会封装在一个独立的工具类里对外只暴露exportReport(...)、importData(...)这类业务函数上层业务代码根本不知道Excel文件长什么样。这样做的收益是哪天客户说“我们要改成导出CSV”我只需要改工具类内部逻辑所有业务调用方都不用动。这种边界意识在项目长期演进中价值非常大。最后再给一个扩展方向QtXlsx不仅能用于桌面程序很多服务端的Qt应用也在用它做报表生成。如果你以后有机会接触到Linux服务器的Qt服务程序只要在Linux上用对应工具链重新编译一遍QtXlsx代码几乎可以原样保留。这也是当初我选择它而不是某个Windows专用方案的最重要原因——跨平台的底子太重要了。