简介：直接编译就能用的Qt5二维码生成工具，支持中文、英文、数字、特殊符号等任意文本转二维码图片。输入内容后实时预览，点击保存即可导出PNG格式图像。核心功能已封装为独立模块（QrCreater.dll/.lib/.h），方便集成到其他Qt或C++项目中复用。配套完整的Visual Studio 2017工程文件（.vcxproj、.vcxproj.filters）、Qt Designer界面文件（QRCodeTool.ui）、资源管理文件（QRCodeTool.qrc）和构建配置，兼容Debug/Release双模式。运行时自动记录日志（QRCodeTool.log），输出调试信息便于排查问题。所有UI交互通过Qt信号槽机制实现，输入响应快、图像更新即时。适用于桌面端快速开发场景，比如内部管理工具、硬件配套软件、扫码功能原型验证、产线设备控制界面等需要嵌入式二维码能力的C++应用。
1. 项目概述：为什么一个“能直接编译就用”的中文二维码工具如此稀缺？
在桌面端C++开发一线干了十多年，我经手过不下二十个需要嵌入二维码功能的项目——从产线PLC上位机的设备ID绑定界面，到医疗设备配套的患者信息快速录入工具，再到某银行内部审计系统的单据溯源模块。几乎每次，团队第一反应都是：“找个开源库集成一下”。结果呢？翻遍GitHub、Qt官方示例、甚至Stack Overflow高赞答案，90%的所谓“Qt二维码方案”要么卡在中文乱码上，要么依赖一堆Python脚本做胶水层，要么干脆只支持ASCII字符集。最典型的一次是给一台国产工业扫码枪写配套配置软件，客户要求输入中文产品型号生成二维码，我们试了qrencode + Qt QImage封装，结果“测试用例”四个字生成的二维码，扫码枪扫出来全是问号；换zxing-cpp，编译链路复杂得像在搭火箭，光是OpenCV依赖就让三个实习生折腾了两天；最后硬着头皮自己撸了个基于libqrencode的Qt封装，才勉强跑通——但那个工程里没有UI、没有日志、没有DLL导出接口，更别说VS工程一键加载了。
所以当我看到这个“Qt5一键生成中文二维码的C++工具包”时，第一反应不是点开看代码，而是立刻建了个空目录，把压缩包解压进去，双击 QRCodeTool.vcxproj ——Visual Studio 2019自动识别Qt版本，点击“本地Windows调试器”，3秒后窗口弹出，输入“你好，世界！✅”，回车，二维码实时渲染，右键保存为PNG，用手机微信一扫，文字完整还原。那一刻我意识到：这不是又一个半成品Demo，而是一个真正被生产环境反复锤炼过的“开箱即用型基建组件”。
它解决的从来不是“能不能生成二维码”这个技术问题，而是“如何让一个非图像处理背景的C++工程师，在15分钟内，把稳定、可靠、支持全中文的二维码能力，塞进他正在写的设备控制软件里”这个现实问题。关键词里的“Qt5二维码”“C++二维码库”“中文二维码生成”，每一个都不是修饰词，而是它必须扛住的三道硬杠杠：Qt5原生生态兼容性、C++零运行时依赖的静态/动态链接能力、UTF-8到QR码数据编码的无损转换闭环。它不追求算法最优（比如Huffman压缩率），但死守“输入什么，扫出来就是什么”的底线。你不需要懂Reed-Solomon纠错原理，也不用研究Mask Pattern选择策略——你只需要知道，当你把QString("订单号：ZK1ctvmWJa8OH5QpJvTR")传给QrCreater::generate()，返回的QImage一定能被任何主流扫码设备正确识别。
这个工具包的价值，恰恰藏在那些“没写进README但实际踩过坑”的细节里：比如.qrc资源文件里预埋了qt.conf防止Qt插件路径错乱；比如QRCodeTool.log里每条记录都带毫秒级时间戳和线程ID，方便多线程调用时归因；比如QrCreater.dll导出函数全部用extern "C"修饰，彻底规避C++ Name Mangling导致的跨编译器调用失败。它不是教科书，而是一份写给同行的、带着体温的工程笔记。
2. 整体架构与设计思路：为什么选libqrencode而不是ZXing或QRCodeGenerator？
整个工具包的骨架非常清晰：上层是Qt Widgets构建的轻量UI（QRCodeTool类），中层是独立封装的二维码核心模块（QrCreater），底层是经过深度定制的libqrencode C语言库。这个三层结构不是拍脑袋定的，而是过去五年在十几个真实项目里用血泪换来的经验沉淀。
先说为什么不选ZXing-cpp。ZXing确实是业界标杆，Java版成熟度极高，但它的C++移植版（zxing-cpp）存在三个致命短板：第一，编译依赖过于沉重——必须引入完整的OpenCV用于图像预处理，而我们的设备配套软件往往运行在无图形界面的嵌入式Linux环境，连X11都不装；第二，中文支持是“伪支持”——它默认将UTF-8字符串当作字节流直接编码，但QR码标准要求对Unicode文本进行ECI（Extended Channel Interpretation）标识，否则扫码设备无法判断字符集，导致中文显示为乱码；第三，API设计偏向Java风格，大量使用智能指针和异常抛出，在Qt信号槽这种异步环境中极易引发内存泄漏或未捕获异常崩溃。我曾在一个医疗PDA项目里强行集成zxing-cpp，最终因为异常传播路径不可控，导致扫码失败时整个UI线程卡死，客户现场验收直接叫停。
再看Qt官方推荐的QRCodeGenerator（Qt 5.12+新增）。它确实简洁，几行代码就能生成QImage，但问题在于：它底层调用的是qrencode的简化封装，且完全不暴露纠错等级、版本号、掩码模式等关键参数。在产线设备场景中，我们经常需要生成固定尺寸（如256×256像素）的二维码，同时保证内容可读性。这时就必须手动指定QR码版本（Version 1~40）和纠错等级（L/M/Q/H）。QRCodeGenerator把这些都封死了，你只能拿到一个“差不多能用”的图，但无法精确控制容错能力——比如客户要求“即使标签被油污覆盖30%，仍能准确识别”，这就必须用M级纠错（15%容错率），而QRCodeGenerator默认用L级（7%），根本达不到要求。
最终选定libqrencode，是权衡后的最优解。它是一个纯C实现的轻量库（不到2000行代码），无任何外部依赖，编译后静态库体积仅120KB；它原生支持ECI机制，通过QRencodeString()函数的hint参数可明确指定QR_MODE_KANJI（日文）或QR_MODE_8（8位字节流），而我们将UTF-8字符串直接以QR_MODE_8传入，配合QR_ECI_UTF8标识，完美解决中文编码问题；最关键的是，它提供了完整的参数控制接口：version（1-40）、level（0=L,1=M,2=Q,3=H）、size（模块像素大小）、margin（边距）、mask（掩码模式）。这些参数在QrCreater.h头文件中被封装为结构体QrConfig，使用者只需修改几个字段，就能生成符合工业场景严苛要求的二维码。
提示：
QrCreater.dll之所以能稳定导出，核心在于所有对外接口均采用C语言ABI。例如导出函数声明为extern "C" __declspec(dllexport) QImage* createQrCode(const char* text, int version, int level)，而非QImage QrCreater::generate(const QString&)。这样做的好处是，无论调用方是VS2015还是VS2022编译的Qt程序，甚至是纯C写的Win32应用，都能通过LoadLibrary+GetProcAddress安全调用，彻底规避C++ ABI不兼容风险。
整个架构的另一大设计亮点是UI与逻辑的彻底解耦。QRCodeTool.ui里所有控件（QLineEdit、QPushButton、QLabel）都不直接操作二维码生成逻辑，而是通过Qt信号槽连接到QRCodeTool类的私有槽函数。当用户在输入框敲下回车，触发on_inputEdit_returnPressed()，该函数只做一件事：提取text()，校验长度（防超长导致生成失败），然后调用QrCreater::generate()获取QImage，最后将图像设置给QLabel的setPixmap()。这种设计让QrCreater模块可以脱离UI独立测试——我们在main.cpp里写了单元测试入口，直接传入中文字符串，断言生成图像的像素尺寸和非透明像素数量，确保核心逻辑在无GUI环境下依然健壮。
3. 核心模块解析：QrCreater.dll的封装逻辑与中文编码实现细节
QrCreater.dll是整个工具包的“心脏”，它的头文件QrCreater.h只有不到150行，却精准覆盖了所有生产环境必需的功能点。我们来逐层拆解它的设计逻辑，尤其聚焦于“中文为何能正确显示”这一核心痛点。
3.1 头文件接口设计：为什么用const char*而非QString？
// QrCreater.h
#ifndef QR_CREATER_H
#define QR_CREATER_H
#include <QImage>
#include <QString>
#ifdef QRCREATER_EXPORTS
#define QRCREATER_API __declspec(dllexport)
#else
#define QRCREATER_API __declspec(dllimport)
#endif
extern "C" {
// 核心生成函数：输入UTF-8 C字符串，输出QImage指针（由调用方负责delete）
QRCREATER_API QImage* createQrCode(const char* text,
int version = 0,
int level = 1,
int size = 4,
int margin = 4);
// 便捷重载：接受QString，内部转UTF-8
QRCREATER_API QImage* createQrCodeFromQString(const QString& text,
int version = 0,
int level = 1,
int size = 4,
int margin = 4);
// 销毁图像内存（必须调用！避免Qt跨DLL内存管理冲突）
QRCREATER_API void destroyQrImage(QImage* image);
// 获取错误信息（线程安全）
QRCREATER_API const char* getLastError();
}
#endif // QR_CREATER_H
这里的关键设计是双接口并存：createQrCode()接受const char*，这是为了兼容纯C环境；createQrCodeFromQString()则是为Qt开发者提供的语法糖。但二者底层都走向同一个实现函数，区别仅在于字符串编码转换。
为什么不用QString作为唯一接口？因为QString是Qt私有类型，其内存布局在不同Qt版本间可能变化。若DLL用Qt5.9编译，而调用方用Qt5.15，QString对象跨DLL传递极可能导致崩溃。而const char*是C语言标准，绝对稳定。我们在createQrCodeFromQString()内部做的转换非常干净：
// QrCreater.cpp 内部实现
QImage* createQrCodeFromQString(const QString& text, int version, int level, int size, int margin) {
QByteArray utf8Bytes = text.toUtf8(); // 强制转UTF-8字节数组
return createQrCode(utf8Bytes.constData(), version, level, size, margin);
}
text.toUtf8()这行代码，就是中文不乱码的基石。它确保无论用户输入框里是简体中文、繁体中文、日文汉字还是emoji，都被无损转换为标准UTF-8字节流，再交给libqrencode处理。
3.2 中文编码的底层实现：ECI标识与libqrencode的协作
libqrencode本身不直接处理Unicode，它只认字节流。要让扫码设备知道“这段字节是UTF-8编码的中文”，必须在QR码数据前插入ECI（Extended Channel Interpretation）头。标准QR码规范定义了ECI标识符26代表UTF-8，但libqrencode默认不启用此功能，需要手动构造数据。
QrCreater的实现如下（精简版）：
QImage* createQrCode(const char* text, int version, int level, int size, int margin) {
if (!text || strlen(text) == 0) {
setError("Input text is null or empty");
return nullptr;
}
// 步骤1：构造带ECI头的UTF-8数据
// ECI头格式：0x1D (ECI indicator) + 0x001A (ECI UTF-8 identifier, little-endian)
// 然后拼接原始UTF-8文本
QByteArray eciData;
eciData.append(0x1D); // ECI indicator
eciData.append(0x1A); // LSB of UTF-8 ECI code
eciData.append(0x00); // MSB of UTF-8 ECI code
eciData.append(text); // 原始UTF-8文本
// 步骤2：调用libqrencode生成QR码
QRcode *qr = QRcode_encodeData(eciData.size(),
(unsigned char*)eciData.constData(),
version,
(QRecLevel)level,
QR_MODE_8); // 关键！指定为8位字节模式
if (!qr) {
setError("QRcode_encodeData failed");
return nullptr;
}
// 步骤3：将libqrencode的QRcode结构转换为QImage
QImage image = qrcodeToQImage(qr, size, margin);
QRcode_free(qr);
return new QImage(image); // 注意：返回new出来的指针，调用方需destroyQrImage()
}
这里有两个决定性细节：
1. ECI头的精确构造：0x1D是QR码标准规定的ECI指示符，0x001A是UTF-8的ECI标识码（小端序存储为0x1A 0x00）。很多开发者只加0x1D，忘了后面两个字节，导致扫码设备无法识别编码，依然显示乱码。
2. QR_MODE_8的强制指定：libqrencode提供多种编码模式（QR_MODE_NUL, QR_MODE_NUM, QR_MODE_AN, QR_MODE_8, QR_MODE_KANJI），其中QR_MODE_8表示“8位字节流”，这是承载UTF-8的唯一正确模式。若误用QR_MODE_AN（字母数字模式），中文会被截断或替换为问号。
3.3 图像转换与内存管理：为什么destroyQrImage()必不可少？
libqrencode生成的QRcode结构体包含一个unsigned char*指针data，指向按行优先排列的二值图像数据（0=白，1=黑）。将其转为QImage需两步：分配QImage内存，然后逐像素填充。
QImage qrcodeToQImage(const QRcode* qr, int moduleSize, int margin) {
int width = qr->width;
int outputWidth = (width + 2 * margin) * moduleSize;
QImage image(outputWidth, outputWidth, QImage::Format_RGB32);
image.fill(Qt::white); // 背景设为白色
QPainter painter(&image);
painter.setPen(Qt::NoPen);
painter.setBrush(Qt::black);
// 遍历QR码数据矩阵
for (int y = 0; y < width; y++) {
for (int x = 0; x < width; x++) {
unsigned char bit = qr->data[y * width + x];
if (bit & 1) { // 模块为黑
QRect rect((x + margin) * moduleSize,
(y + margin) * moduleSize,
moduleSize, moduleSize);
painter.drawRect(rect);
}
}
}
return image;
}
这个函数返回的是栈上QImage对象的拷贝，但createQrCode()函数内部new QImage(image)创建的是堆内存对象。为什么这么做？因为QImage的隐式共享（implicit sharing）机制在跨DLL边界时不可靠。如果直接返回QImage对象，Qt可能在DLL内部触发detach()操作，尝试修改引用计数，而该计数器位于DLL的内存空间，调用方进程无法安全访问，导致崩溃。因此，我们强制在DLL内new，并提供destroyQrImage()供调用方清理：
void destroyQrImage(QImage* image) {
if (image) {
delete image;
}
}
注意：在Qt Creator中调试时，若忘记调用
destroyQrImage()，会触发Qt的内存泄漏检测器报警。我们在QRCodeTool.cpp的on_saveButton_clicked()槽函数里，严格遵循“生成→使用→销毁”三步曲，确保每个QImage*都有且仅有一次destroyQrImage()调用。
4. VS工程构建详解：从零配置到Debug/Release双模式的完整链路
这个工具包的VS工程（QRCodeTool.vcxproj）之所以能做到“双击即编译”，核心在于它把所有构建依赖都固化在了项目文件内部，而非依赖全局环境变量。下面我带你走一遍从空白VS安装到成功运行的全流程，重点揭示那些文档里不会写、但实际踩坑最多的配置点。
4.1 Qt环境集成：为什么不用Qt VS Tools插件？
很多教程推荐安装“Qt Visual Studio Tools”插件，让它自动管理Qt版本。但在企业级开发中，这恰恰是最大的隐患。插件会修改全局PATH和QTDIR，当你的机器上同时存在Qt5.9、Qt5.15、Qt6.2多个版本时，插件极易混淆，导致Debug模式用Qt5.9编译，Release模式却链接Qt5.15的库，引发QMetaObject虚表错乱等深层崩溃。
本工程采用纯手工Qt集成，所有路径硬编码在.vcxproj文件中。打开项目属性页（右键项目→属性），关键配置如下：
- 常规 → 平台工具集：
v142（对应VS2019）或v141（对应VS2017），确保与你的VS版本一致。 - 常规 → Windows SDK版本：
10.0.19041.0（推荐，兼容Win7及以上）。 -
C/C++ → 常规 → 附加包含目录：
$(QTDIR)\include;$(QTDIR)\include\QtWidgets;$(QTDIR)\include\QtGui;$(QTDIR)\include\QtCore;$(QTDIR)\mkspecs\win32-msvc
这里$(QTDIR)是一个自定义宏，在项目属性页的“配置属性→常规→Qt安装路径”中设置，例如C:\Qt\5.15.2\msvc2019_64。绝不使用%QTDIR%环境变量，避免污染。 -
链接器 → 常规 → 附加库目录：
$(QTDIR)\lib -
链接器 → 输入 → 附加依赖项（Debug模式）：
Qt5Cored.lib;Qt5Widgetsd.lib;Qt5Guid.lib
（Release模式则为Qt5Core.lib;Qt5Widgets.lib;Qt5Gui.lib）
最关键的一步是Qt头文件的预编译处理。Qt的moc（Meta-Object Compiler）必须在编译前运行，生成moc_QRCodeTool.cpp等文件。本工程在.vcxproj中显式定义了CustomBuildStep：
<CustomBuild Include="QRCodeTool.h">
<Message>Running moc on %(Identity)</Message>
<Command>"$(QTDIR)\bin\moc.exe" -DUNICODE -DWIN32 -DQT_CORE_LIB -DQT_GUI_LIB -DQT_WIDGETS_LIB -DQT_NO_DEBUG "-I$(QTDIR)\include" "-I$(QTDIR)\include\QtWidgets" "-I$(QTDIR)\include\QtGui" "-I$(QTDIR)\include\QtCore" "-I$(QTDIR)\mkspecs\win32-msvc" "%(FullPath)" -o "$(IntDir)moc_%(Filename).cpp"</Command>
<Outputs>$(IntDir)moc_%(Filename).cpp</Outputs>
<AdditionalInputs>$(QTDIR)\bin\moc.exe;%(FullPath)</AdditionalInputs>
</CustomBuild>
这段XML确保VS在编译QRCodeTool.h前，自动调用moc.exe生成对应的moc_QRCodeTool.cpp，并将其加入编译队列。你无需手动运行moc，也无需在源文件中添加#include "moc_QRCodeTool.cpp"——VS会自动处理。
4.2 Debug与Release双模式的差异化配置
Debug和Release模式不只是优化开关的区别，它们在Qt项目中涉及符号调试、运行时库、Qt库链接方式三大差异：
| 配置项 | Debug模式 | Release模式 | 为什么这样设 |
|---|---|---|---|
| C/C++ → 优化 | 禁用 (/Od) | 最大化速度 (/O2) | Debug需保留完整符号信息，便于断点调试 |
| C/C++ → 代码生成 → 运行时库 | 多线程调试DLL (/MDd) | 多线程DLL (/MD) | /MDd链接msvcrtd.dll，含调试符号；/MD链接msvcrt.dll，体积更小 |
| 链接器 → 调试 → 生成调试信息 | 是 (/DEBUG) | 否 | Debug需生成.pdb文件，Release可省略以减小体积 |
| Qt库链接 | Qt5Cored.lib等带d后缀的库 | Qt5Core.lib等无d后缀的库 | Qt的Debug库包含额外断言和检查，Release库已移除 |
这些配置在.vcxproj中通过<ConfigurationType>和<PlatformToolset>条件块精确控制。例如，Release模式的链接器设置：
<ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Release|Win32'">
<LinkIncremental>false</LinkIncremental>
<Linker>
<GenerateDebugInformation>false</GenerateDebugInformation>
<SubSystem>Windows</SubSystem>
</Linker>
</ItemDefinitionGroup>
实操心得：在首次编译Release版本时，务必检查生成目录下的
QRCodeTool.exe文件大小。正常应为1.2MB左右（含Qt库）。若小于800KB，大概率是链接了静态Qt库（/MT），导致QApplication初始化失败，程序一闪而退。此时需回到“运行时库”设置，确认是/MD而非/MT。
4.3 资源文件（.qrc）与UI文件（.ui）的自动化构建
QRCodeTool.qrc和QRCodeTool.ui是Qt项目的灵魂，它们的构建流程被深度集成到VS中：
-
.qrc资源文件：VS通过<CustomBuild>调用rcc.exe（Qt Resource Compiler）将.qrc编译为qrc_QRCodeTool.cpp，该文件包含所有资源（图标、字体）的二进制数据，编译进EXE。本工程的.qrc仅包含一个qt.conf文件，内容为：
ini [Paths] Plugins = plugins
这行配置强制Qt在EXE同目录下的plugins子目录中查找平台插件（如qwindows.dll），避免因系统环境变量混乱导致“无法启动”错误。 -
.ui界面文件：VS调用uic.exe（User Interface Compiler）将QRCodeTool.ui转换为ui_QRCodeTool.h，这是一个纯C++头文件，定义了Ui::QRCodeTool命名空间下的setupUi()函数。QRCodeTool.h中通过#include "ui_QRCodeTool.h"引入，并在构造函数中调用ui->setupUi(this)完成界面初始化。
整个流程完全自动化：你修改.ui文件，保存，VS下次编译时自动触发uic；你添加新图标到.qrc，保存，VS自动触发rcc。无需手动执行任何命令行工具。
5. 实操过程：从编译运行到集成复用的完整步骤
现在，让我们把前面所有的理论知识，落地为可立即执行的操作指南。我会以一个真实的场景为例：假设你正在为一台国产数控机床开发配套的工单管理软件，需要在软件界面上增加一个“生成加工指令二维码”按钮，点击后将当前工单号（如"G2023-08-001-中文测试"）生成二维码并显示在对话框中。整个过程分为三步：编译运行原工具、提取DLL复用、集成到你的工程。
5.1 第一步：编译并验证原工具包（5分钟）
-
准备环境：
- 安装Visual Studio 2017或更高版本（推荐VS2019）。
- 安装Qt 5.15.2（MSVC 2019 64-bit版本），路径记为C:\Qt\5.15.2\msvc2019_64。
- 下载工具包压缩包，解压到任意目录，例如D:\QRCodeTool。 -
配置Qt路径：
- 打开D:\QRCodeTool\QRCodeTool.vcxproj，VS自动加载项目。
- 右键项目→“属性”→“配置属性”→“常规”→找到“Qt安装路径”，填入C:\Qt\5.15.2\msvc2019_64。
- 点击“确定”保存。 -
编译运行：
- 在VS顶部菜单栏，将解决方案配置改为Debug，平台改为x64。
- 按Ctrl+Shift+B编译，等待“生成: 全部成功”。
- 按F5启动调试，窗口弹出。
- 在输入框输入测试中文✅123，回车，右侧立即显示二维码。
- 点击“保存图片”，选择路径，生成output.png。
- 用手机微信扫描，确认文字完整还原。
注意：若编译报错
LNK1104: 无法打开文件 'Qt5Cored.lib'，说明Qt路径配置错误，请重新检查“Qt安装路径”是否指向msvc2019_64目录，而非mingw或其他版本。
5.2 第二步：提取DLL模块供其他项目复用（3分钟）
原工具包的QrCreater.dll已编译好，位于D:\QRCodeTool\Release\目录（Debug模式在Debug\目录）。复用它只需三步：
-
复制必要文件：
- 将D:\QRCodeTool\Release\QrCreater.dll复制到你的目标工程目录，例如C:\MyCNCApp\libs\。
- 将D:\QRCodeTool\QrCreater.h和D:\QRCodeTool\QrCreater.lib（导入库）一并复制过去。 -
在你的VS工程中配置：
- 右键你的项目→“属性”→“C/C++ → 常规 → 附加包含目录”，添加C:\MyCNCApp\libs。
- “链接器 → 常规 → 附加库目录”，添加C:\MyCNCApp\libs。
- “链接器 → 输入 → 附加依赖项”，添加QrCreater.lib。 -
编写调用代码（在你的
MainWindow.cpp中）：
```cpp
#include “QrCreater.h”
#include
void MainWindow::on_generateQrButton_clicked() {
QString orderNo = ui->orderLineEdit->text(); // 获取工单号
if (orderNo.isEmpty()) return;
// 调用DLL生成二维码
QImage* qrImage = createQrCodeFromQString(orderNo, 1, 1, 6, 4); // Version 1, M-level, 6px/module
if (!qrImage) {
QMessageBox::warning(this, "错误", QString("生成失败：%1").arg(getLastError()));
return;
}
// 显示在QLabel上
ui->qrLabel->setPixmap(QPixmap::fromImage(*qrImage));
// 记得销毁！
destroyQrImage(qrImage);
}
```
5.3 第三步：高级集成技巧与性能调优
在真实产线环境中，你可能会遇到更高阶的需求，这里分享几个实战技巧：
技巧1：批量生成二维码并导出为PDF报告
有些客户要求将100个工单号批量生成二维码，汇总成PDF。QrCreater.dll本身不提供PDF功能，但你可以轻松组合：
// 使用QPdfWriter（Qt自带）
QPdfWriter pdf("report.pdf");
pdf.setPageSize(QPageSize::A4);
QPainter painter(&pdf);
painter.setFont(QFont("SimSun", 10)); // 设置中文字体
int y = 50;
for (const QString& no : orderList) {
QImage* img = createQrCodeFromQString(no, 2, 2, 4, 2); // Version 2, Q-level
if (img) {
painter.drawText(50, y, no); // 工单号文字
painter.drawImage(200, y-30, *img); // 二维码图像
y += 120;
destroyQrImage(img);
}
}
技巧2：提升生成速度（针对高频调用场景）
若你的软件每秒需生成10+个二维码（如实时监控大屏），可预分配QImage缓冲区，避免频繁内存分配：
// 在类成员中缓存
QImage m_qrBuffer;
void MyWidget::fastGenerate(const QString& text) {
QImage* img = createQrCodeFromQString(text);
if (img) {
m_qrBuffer = std::move(*img); // 移动语义，避免深拷贝
destroyQrImage(img);
ui->label->setPixmap(QPixmap::fromImage(m_qrBuffer));
}
}
技巧3：自定义二维码样式（添加Logo）
QrCreater.dll生成的是纯黑白二维码，若需在中心嵌入公司Logo，可在生成后用QPainter绘制：
QImage withLogo = *qrImage; // 假设qrImage是生成的图像
QPainter p(&withLogo);
QPixmap logo(":/images/logo.png");
p.drawPixmap(
(withLogo.width() - logo.width()) / 2,
(withLogo.height() - logo.height()) / 2,
logo
);
p.end();
ui->label->setPixmap(QPixmap::fromImage(withLogo));
6. 常见问题与排查技巧实录：那些让你加班到凌晨的坑
在将这个工具包交付给5个不同客户的过程中，我整理了一份高频问题清单。这些问题看似琐碎，但每一个都曾让我在客户现场对着黑屏的二维码调试到凌晨两点。以下是最典型的6个问题及根治方案。
6.1 问题：中文生成的二维码，手机扫出来是乱码或问号
现象：输入“测试”生成二维码，微信扫描显示“测试”。
根因分析：这是UTF-8编码未被正确识别的典型表现。扫码设备看到的是原始字节流0xE6 0xB5 0x8B 0xE8 AF 0xA6，但未被告知这是UTF-8，于是按Latin-1解码，得到乱码。
排查步骤：
1. 用在线QR码解析工具（如https://www.onlinebarcodereader.com/）上传生成的PNG，查看原始数据。若显示e6b58be8af95，说明编码正确；若显示测试，说明编码已错。
2. 检查QrCreater.cpp中ECI头是否完整。常见错误是漏掉0x00字节，只写了0x1D 0x1A。
根治方案：
- 确保createQrCode()函数中ECI头构造为4字节：0x1D, 0x1A, 0x00, ...。
- 在QRCodeTool.cpp中添加日志，打印输入文本的UTF-8十六进制：
cpp qDebug() << "Input UTF-8 hex:" << text.toUtf8().toHex();
正常应输出e6b58be8af95，若输出ceb2c3a4，说明输入框本身未启用UTF-8。
6.2 问题：编译时报错LNK2019: 无法解析的外部符号 __imp__createQrCode@16
现象：你的工程能编译通过，但链接时报LNK2019，找不到createQrCode函数。
根因分析：这是C++ Name Mangling导致的。如果你的调用方代码用了extern "C"声明，但DLL导出时没用，或者反之，就会出现符号不匹配。
排查步骤：
1. 用dumpbin /exports QrCreater.dll命令查看DLL实际导出的函数名。若显示?createQrCode@@YAPAVQImage@@PBHIIH@Z，说明是C++ Mangling；若显示createQrCode，才是正确的C导出。
2. 检查QrCreater.h中extern "C"是否包裹了整个函数声明块。
根治方案：
- 严格遵循QrCreater.h中的extern "C"写法，确保所有导出函数都在其作用域内。
- 在调用方工程中，#include "QrCreater.h"前，必须定义QRCREATER_EXPORTS宏（仅用于DLL自身编译），调用方无需定义。
6.3 问题：程序运行一闪而退，无任何错误提示
现象：双击QRCodeTool.exe，窗口闪一下就消失。
根因分析：Qt应用程序启动失败的最常见原因是平台插件缺失。QApplication构造时需加载qwindows.dll，若找不到，会静默退出。
排查步骤：
1. 在命令行中运行：D:\QRCodeTool\Release\QRCodeTool.exe，观察控制台是否有错误输出。
2. 若看到Failed to load platform plugin "windows"，则证实是插件问题。
根治方案：
- 确保QRCodeTool.qrc中包含qt.conf，且内容正确。
- 或手动创建plugins目录：在Release目录下新建plugins\platforms\子目录，将C:\Qt\5.15.2\msvc2019_64\plugins\platforms\qwindows.dll复制进去。
6.4 问题：Debug模式正常，Release模式生成的二维码模糊不清
现象：Release版二维码边缘有锯齿，扫描成功率下降。
根因分析：Release模式启用了编译器优化（/O2），可能影响QPainter的抗锯齿设置。
排查步骤：
1. 在qrcodeToQImage()函数中，QPainter构造后，添加：
cpp painter.setRenderHint(QPainter::Antialiasing, true); painter.setRenderHint(QPainter::SmoothPixmapTransform, true);
2. 编译Release版测试。
根治方案：
- 在qrcodeToQImage()开头强制启用抗锯齿：
cpp QPainter painter(&image); painter.setRenderHint(QPainter::Antialiasing, true); painter.setRenderHint(QPainter::TextAntialiasing, true); painter.setRenderHint(QPainter::SmoothPixmapTransform, true);
6.5 问题：日志文件QRCodeTool.log为空或不更新
现象：程序运行后，QRCodeTool.log文件存在但大小为0。
根因分析：Qt的日志系统默认缓冲，若程序异常退出，缓冲区未刷新。
根治方案：
- 在main.cpp中，QApplication构造后，添加强制刷新：
cpp qInstallMessageHandler(customMessageHandler); // 添加这行，确保日志实时写入 qSetMessagePattern("%{time yyyy-MM-dd hh:mm:ss.zzz} %{type} %{function} %{message}");
6.6 问题：在无Qt环境的客户机器上运行报错“缺少Qt5Core.dll”
现象：将QRCodeTool.exe拷贝到客户电脑，提示“找不到Qt5Core.dll”。
根因分析：Release版EXE动态链接Qt DLL，但客户机器未安装Qt。
根治方案（二选一）：
- 方案A（推荐）：部署Qt运行时
将C:\Qt\5.15.2\msvc2019_64\bin\目录下的Qt5Core.dll, Qt5Gui.dll, Qt5Widgets.dll，以及plugins\platforms\qwindows.dll，全部复制到你的EXE同目录。目录结构为：
QRCodeTool.exe Qt5Core.dll Qt5Gui.dll Qt5Widgets.dll \plugins\platforms\qwindows.dll
- 方案B：静态编译Qt（适合对体积不敏感的场景）
重新编译Qt源码，启用-static选项，然后用静态Qt编译你的工程，生成的EXE体积约30MB，但无需任何DLL。
最后分享一个小技巧：在
QRCodeTool.cpp的on_saveButton_clicked()函数中，我加入了自动校验逻辑——保存PNG后，立即用QImageReader重新加载该文件，并调用QImage::isNull()检查是否损坏。若损坏，则弹窗提示“保存失败，请检查磁盘空间”，这比让用户反馈“二维码打不开”要主动得多。真正的工程化，就藏在这些不起眼的细节里。
简介：直接编译就能用的Qt5二维码生成工具，支持中文、英文、数字、特殊符号等任意文本转二维码图片。输入内容后实时预览，点击保存即可导出PNG格式图像。核心功能已封装为独立模块（QrCreater.dll/.lib/.h），方便集成到其他Qt或C++项目中复用。配套完整的Visual Studio 2017工程文件（.vcxproj、.vcxproj.filters）、Qt Designer界面文件（QRCodeTool.ui）、资源管理文件（QRCodeTool.qrc）和构建配置，兼容Debug/Release双模式。运行时自动记录日志（QRCodeTool.log），输出调试信息便于排查问题。所有UI交互通过Qt信号槽机制实现，输入响应快、图像更新即时。适用于桌面端快速开发场景，比如内部管理工具、硬件配套软件、扫码功能原型验证、产线设备控制界面等需要嵌入式二维码能力的C++应用。
扫一扫
181
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
