1. 项目概述：一个桌面端二维码生成器的诞生

最近在整理个人工具箱时，发现一个高频需求：快速生成一个自定义内容的二维码，比如把一段文本、一个网址甚至是一张名片信息转换成二维码图片。虽然网页版工具很多，但考虑到数据隐私和离线使用的便利性，我决定自己动手，用 Qt/C++ 撸一个本地化的二维码生成器。这个项目麻雀虽小，五脏俱全，它不仅能让你得到一个实用的工具，更能带你走一遍 Qt 应用开发从环境搭建、第三方库集成、核心逻辑实现到最终打包发布的完整流程。无论你是刚接触 Qt 想找个练手项目，还是想了解如何将 C++ 库集成到 GUI 程序中，这个项目都能给你提供清晰的参考。最终，我会把完整的工程源码链接附在文末，你可以直接拿去研究、修改或二次开发。

2. 核心思路与技术选型

2.1 为什么选择 Qt 和 C++？

首先得说说技术栈的选择。桌面 GUI 开发有很多路，比如 Electron、PyQt、WinForms 等。我选择 Qt/C++ 主要基于几点考量：

1. 性能与资源占用：C++ 是编译型语言，生成的本地代码执行效率高，内存占用可控。对于一个二维码生成工具，核心的编码计算可能涉及大量位运算和矩阵操作，C++ 在这方面有天然优势。生成的程序是单个可执行文件，启动快，不依赖庞大的运行时环境。
2. Qt 框架的成熟度：Qt 不仅仅是一个 GUI 库，它提供了一整套完整的应用程序框架，包括信号槽（用于对象间通信）、模型/视图（用于数据展示）、国际化、样式表等。用它开发跨平台应用非常方便，一套代码稍作调整就能编译运行在 Windows、macOS 和 Linux 上。
3. 开发体验与生态：Qt Creator IDE 对 Qt 开发的支持非常友好，集成了设计器、调试器和帮助文档。虽然 Qt 本身不直接提供二维码生成功能，但其良好的扩展性使得集成第三方 C/C++ 库（如 libqrencode）变得相对简单。

2.2 二维码生成库的选择：libqrencode

Qt 没有内置二维码功能，所以我们需要一个可靠的二维码编码库。主流的 C/C++ 二维码库有 libqrencode 和 ZXing（Zebra Crossing）。这里我选择了libqrencode，原因如下：

• 专注编码：libqrencode 只做一件事——将文本数据编码成二维码的符号（Symbol），即生成代表黑白色块的二维数组。它不负责渲染成图片，这正好给了我们最大的灵活性，可以用 Qt 的绘图功能自由地渲染。
• 轻量高效：代码库小巧，接口简洁，生成的二维码符号数据可以直接用于后续的图形绘制。
• 广泛使用：经过多年考验，稳定可靠，很多开源项目都在使用。

ZXing 功能更强大（支持编码和解码，支持多种条码格式），但库体积更大，对于只需要生成功能的我们来说，libqrencode 更合适。

2.3 整体架构设计

整个工具的设计非常直观，遵循典型的 MVC（模型-视图-控制器）简化模式：

1. 模型（Model）：libqrencode 库。它接收我们输入的字符串（文本、URL等），根据选定的纠错等级、版本（尺寸）等参数，进行编码计算，输出一个二维数组（QRcode 结构体），这个数组就是二维码的“数据模型”。
2. 视图（View）：Qt 的 QWidget 界面。提供一个文本框让用户输入内容，一些控件（如下拉框、复选框）用于选择纠错等级、尺寸、边距等参数，还有一个 QLabel 或自定义的 QWidget 用于预览生成的二维码图片。
3. 控制器（Controller）：连接模型和视图的 Qt 代码。具体来说，就是“生成”按钮的clicked信号所连接的槽函数。这个函数会从界面控件获取用户输入和参数，调用 libqrencode 的接口进行编码，然后将得到的 QRcode 数据模型，通过 Qt 的 QPainter 等绘图工具，渲染成 QPixmap，最后显示在界面的预览区域。同时，还会实现“保存”功能，将 QPixmap 保存为 PNG 等格式的图片文件。

3. 开发环境搭建与工程配置

3.1 Qt 开发环境安装避坑指南

对于新手，安装 Qt 是第一步，也是最容易踩坑的一步。这里提供两种主流方案：

方案一：使用 Qt 官方安装器（Qt Online Installer）这是最推荐的方式，灵活且可控。

1. 前往 Qt 官网下载在线安装器。注意，官网可能需要注册账号，这是正常流程。
2. 运行安装器。第一个关键选择是“镜像源”。如果默认源下载慢，可以尝试添加国内的镜像源，例如中国科技大学的镜像，这能极大提升下载速度。在安装器的设置（Settings）里可以添加。
3. 选择组件时，对于这个项目，你需要：
   • Qt 版本：选择一个长期支持（LTS）版本，如 Qt 5.15.x 或 Qt 6.2+。LTS 版本更稳定。我项目中使用的是 Qt 5.15.2。
   • 编译器：在 Windows 上，选择与你 Visual Studio 版本对应的 MinGW 或 MSVC。如果你没有 VS，就选 MinGW。在 macOS 上通常选 Clang，Linux 上选 GCC。
   • 额外工具：务必勾选Qt Creator（这是我们的 IDE）和对应版本的Qt Charts（如果你未来想扩展功能可能会用到，但本项目非必需）。
4. 安装路径不要有中文和空格。

注意：安装过程中可能会提示安装 “Microsoft Visual C++ Redistributable”，这是运行 MSVC 编译的程序所必需的，一定要同意安装。否则将来运行编译好的程序可能会报错 “This application failed to start because no Qt platform plugin could be initialized” 或缺少 DLL。

方案二：使用包管理器（Linux/macOS）在 Ubuntu/Debian 上可以用sudo apt install qt5-default qtcreator，在 macOS 上可以用brew install qt5。这种方式简单，但可能版本不是最新的。

3.2 集成 libqrencode 到 Qt 项目

libqrencode 通常以源码形式提供。我们需要将其编译成库，然后让 Qt 项目链接它。

步骤 1：获取并编译 libqrencode

1. 从 GitHub 或其官网下载 libqrencode 源码包。
2. 编译：
   • Linux/macOS：在源码目录打开终端，执行经典的./configure,make,sudo make install三部曲。默认会安装到/usr/local下。
   • Windows（MinGW）：在 Qt Creator 的“构建套件”中选择 MinGW，然后打开源码目录下的.pro文件（如果有）或用 CMake 构建。更简单的方法是，直接使用别人编译好的预编译库（.a 或 .dll 和 .lib 文件）。

步骤 2：在 Qt 项目 (.pro 文件) 中配置假设你把编译好的libqrencode.a（静态库）或qrencode.dll（动态库）以及头文件放到了项目目录的thirdparty/qrencode文件夹下。 在你的 Qt 项目文件（.pro）中添加以下配置：

# 包含头文件路径 INCLUDEPATH += $$PWD/thirdparty/qrencode/include # 链接库文件路径和库名 # 如果是静态库（.a 或 .lib） LIBS += -L$$PWD/thirdparty/qrencode/lib -lqrencode # 如果是 Windows 下的动态库，可能需要额外指定导入库 win32: LIBS += -L$$PWD/thirdparty/qrencode/lib -lqrencode # 同时，确保运行时能找到.dll。可以将.dll复制到构建输出目录，或添加到系统PATH。

步骤 3：验证集成在代码中包含头文件#include <qrencode.h>，并尝试声明一个QRcode指针变量。如果能编译通过，说明环境配置成功。

3.3 解决中文乱码与路径问题

这是一个经典的坑，尤其在 Windows 下。

• 源码文件编码：确保你的.cpp和.h文件保存为UTF-8 with BOM编码（在 Qt Creator 中，编辑 -> Select Encoding... 可以转换）。这是 Qt 在 Windows 上处理中文字符串常量最兼容的方式。
• 字符串处理：在代码中，如果需要将包含中文的 QString 传递给 libqrencode（它通常接受const char*），需要进行正确的转换：

  QString text = u8"你好世界"; // UTF-8 字符串 QByteArray ba = text.toUtf8(); // 转换为 UTF-8 编码的 QByteArray const char *c_str = ba.constData(); // 获取 C 风格字符串指针 // 将 c_str 传递给 libqrencode

• 文件路径：在保存图片时，使用QFileDialog::getSaveFileName获取的路径是 QString。使用QFile或QPixmap::save时直接使用即可，它们内部会处理。避免使用std::string和const char*来操作包含中文的路径，容易出错。

4. 核心功能模块实现详解

4.1 用户界面设计与布局

界面力求简洁实用。使用 Qt Designer 拖拽完成，对应的.ui文件会被编译成头文件。

• 主窗口：一个QMainWindow。
• 中央部件：使用一个QWidget作为中心容器，采用QVBoxLayout垂直布局。
• 输入区：顶部放置一个QLabel（“输入内容：”）和一个QTextEdit（允许多行输入）。QTextEdit比QLineEdit更适合可能较长的文本。
• 参数控制区：使用QGroupBox分组，内部用QFormLayout或网格布局。
  • QComboBox：用于选择纠错等级（L, M, Q, H）。
  • QSpinBox：用于选择二维码版本（1-40，控制尺寸），或者直接选择像素尺寸。
  • QSpinBox：用于设置边距（Quiet Zone）。
  • QCheckBox：是否在二维码中央添加 Logo 图片。
• 预览区：用一个QLabel来显示二维码图片。将其scaledContents属性设为true，并设置一个固定尺寸或最小尺寸，以便预览。
• 按钮区：水平布局，放置两个QPushButton：“生成二维码”和“保存图片”。
• 状态栏：QMainWindow自带的 statusBar，用于显示提示信息，如“生成成功”、“保存路径”等。

4.2 二维码生成的核心逻辑

这是项目的引擎，在“生成”按钮的槽函数中实现。

void MainWindow::onGenerateButtonClicked() { // 1. 获取输入文本 QString inputText = ui->textEdit->toPlainText().trimmed(); if (inputText.isEmpty()) { QMessageBox::warning(this, "警告", "输入内容不能为空！"); return; } // 2. 获取参数 QRecLevel correctionLevel = static_cast<QRecLevel>(ui->correctionLevelCombo->currentIndex()); // 纠错等级 int margin = ui->marginSpinBox->value(); // 边距 bool useLogo = ui->logoCheckBox->isChecked(); // 是否使用Logo // 版本号可以自动确定，也可以手动指定。libqrencode 提供了 QRcode_encodeString 自动选择最小版本。 int version = 0; // 0 表示自动选择 // 3. 调用 libqrencode 进行编码 QByteArray ba = inputText.toUtf8(); QRcode *qrcode = QRcode_encodeString(ba.constData(), version, correctionLevel, QR_MODE_8, 1); if (!qrcode) { QMessageBox::critical(this, "错误", "二维码生成失败！输入内容可能过长或包含不支持字符。"); return; } // 4. 将 QRcode 数据渲染为 QImage QImage qrImage = renderQRCode(qrcode, margin, useLogo); // 见下文 renderQRCode 函数 // 5. 释放 QRcode 资源 QRcode_free(qrcode); // 6. 显示预览 QPixmap pixmap = QPixmap::fromImage(qrImage); ui->previewLabel->setPixmap(pixmap.scaled(ui->previewLabel->size(), Qt::KeepAspectRatio, Qt::SmoothTransformation)); // 7. 更新状态 m_currentQRImage = qrImage; // 成员变量，用于保存 ui->statusBar->showMessage("二维码生成成功", 3000); }

关键的renderQRCode函数负责将QRcode结构体的数据画出来：

QImage MainWindow::renderQRCode(QRcode *qrcode, int margin, bool useLogo) { int qrWidth = qrcode->width; int imgSize = qrWidth + 2 * margin; // 最终图片边长 QImage image(imgSize, imgSize, QImage::Format_ARGB32); image.fill(Qt::white); // 白色背景 QPainter painter(&image); painter.setPen(Qt::NoPen); painter.setBrush(Qt::black); // 黑色模块 // 绘制二维码模块 for (int y = 0; y < qrWidth; ++y) { for (int x = 0; x < qrWidth; ++x) { if (qrcode->data[y * qrWidth + x] & 1) { // 检查模块是否为黑色 painter.drawRect(margin + x, margin + y, 1, 1); // 每个模块画一个1x1的矩形 } } } // 可选：绘制Logo if (useLogo && !m_logoImage.isNull()) { // 计算Logo大小，通常为二维码宽度的1/5到1/4 int logoSize = qrWidth / 5; int logoPos = margin + (qrWidth - logoSize) / 2; // 画一个白色圆角矩形作为Logo底衬，避免干扰识别 painter.setBrush(Qt::white); painter.drawRoundedRect(logoPos-2, logoPos-2, logoSize+4, logoSize+4, 5, 5); // 绘制Logo图片 painter.drawImage(QRect(logoPos, logoPos, logoSize, logoSize), m_logoImage.scaled(logoSize, logoSize, Qt::KeepAspectRatio, Qt::SmoothTransformation)); } painter.end(); return image; }

4.3 图片保存与高级功能

保存功能实现起来很简单：

void MainWindow::onSaveButtonClicked() { if (m_currentQRImage.isNull()) { QMessageBox::warning(this, "警告", "请先生成二维码！"); return; } QString fileName = QFileDialog::getSaveFileName(this, "保存二维码图片", QDir::homePath(), "PNG Images (*.png);;JPEG Images (*.jpg *.jpeg);;All Files (*)"); if (!fileName.isEmpty()) { if (m_currentQRImage.save(fileName)) { ui->statusBar->showMessage("已保存至: " + fileName, 5000); } else { QMessageBox::critical(this, "错误", "保存文件失败！"); } } }

高级功能扩展思路：

1. 颜色自定义：在renderQRCode函数中，将Qt::black和Qt::white替换为从颜色选择器（QColorDialog）获取的颜色。
2. 样式美化：绘制圆点而非方块。在drawRect处改为drawEllipse，并计算好位置和大小。也可以尝试绘制带圆角的模块。
3. Logo 集成：如上代码所示，在二维码中心绘制一个缩小的 Logo 图片。关键是 Logo 不能太大，且需要留白底，否则会影响识别率。m_logoImage可以通过一个“加载 Logo”按钮用QFileDialog::getOpenFileName和QImage::load来设置。
4. 批量生成：读取一个文本文件（每行一个内容），循环调用生成和保存逻辑。

5. 项目构建、打包与部署

5.1 编译与调试

在 Qt Creator 中，选择合适的构建套件（Kit），点击“构建”即可。如果遇到链接错误，回头检查.pro文件中的LIBS和INCLUDEPATH设置是否正确，库文件路径是否存在。

实操心得：在 Windows 上使用 MSVC 编译时，如果 libqrencode 是用 MinGW 编译的，可能会因运行时库不兼容而链接失败。最好保持编译环境一致，即都用 MSVC 或都用 MinGW 编译所有依赖库。

5.2 程序打包发布（以 Windows 为例）

Qt 程序编译后，直接双击.exe通常会失败，因为它依赖一堆 Qt 的 DLL。我们需要将这些依赖一起打包。

方法一：使用windeployqt工具（推荐）这是 Qt 自带的部署工具，能自动拷贝大部分依赖。

1. 在 Qt 安装目录下的bin文件夹里找到windeployqt.exe（例如C:\Qt\5.15.2\msvc2019_64\bin）。
2. 打开命令行（CMD），切换到你的程序编译输出目录（release文件夹）。
3. 执行命令：windeployqt your_app_name.exe
4. 工具会自动扫描 exe 所需的 Qt 模块，并将对应的 DLL、插件、翻译文件等复制到当前目录。
5. 别忘了手动复制你依赖的第三方库，比如qrencode.dll（如果有的话）。

方法二：手动拷贝如果不确定或windeployqt有遗漏，可以手动将以下 DLL 从 Qt 的bin目录复制到 exe 同目录：

• 核心：Qt5Core.dll,Qt5Gui.dll,Qt5Widgets.dll
• 平台插件：需要创建一个platforms文件夹，里面放入qwindows.dll（Windows 平台）。
• 如果用了图片格式支持（如 PNG），可能需要Qt5Png.dll或通过plugins/imageformats文件夹提供。
• 你项目依赖的其他 Qt 模块的 DLL。

验证：将整个文件夹（包含 exe 和所有 DLL、插件文件夹）复制到一个新的、没有 Qt 开发环境的电脑上，运行 exe，如果能正常启动，说明打包成功。

5.3 跨平台注意事项

• Linux：通常使用linuxdeployqt或 AppImage 工具链进行打包。也可以直接分发源码，让用户用qmake和make编译，前提是他们安装了 Qt 开发库和 libqrencode。
• macOS：使用macdeployqt工具创建.app捆绑包。命令类似：macdeployqt YourApp.app。
• 路径分隔符：在代码中处理文件路径时，使用QDir::separator()或“/”（Qt 内部会处理），避免直接使用“\”，以保证跨平台兼容性。

6. 常见问题排查与优化技巧

6.1 编译与链接问题速查表

6.2 性能与资源优化

• 异步生成：如果生成非常复杂的二维码（版本高、内容长）导致界面卡顿，可以将QRcode_encodeString这个耗时操作放到一个单独的QThread线程中，生成完毕后再通过信号槽通知主线程更新 UI。
• 图片缩放质量：在预览时，QLabel缩放图片使用Qt::SmoothTransformation以获得更好的视觉效果。但在保存最终图片时，应保存原始分辨率的图像，避免缩放带来的模糊。
• 内存管理：确保每次生成新的二维码前，调用QRcode_free()释放上一次的QRcode结构体，防止内存泄漏。

6.3 用户体验提升点

1. 实时预览：可以将“生成”按钮改为实时响应。使用QTimer防抖，在用户停止输入后延迟几百毫秒自动触发生成，提升交互流畅度。
2. 参数预设：提供几个常用预设（如“Wi-Fi网络”、“联系人名片”），点击后自动填充格式化的文本和推荐参数。
3. 历史记录：将最近生成过的文本内容保存在QSettings或一个小型数据库中，方便用户再次使用。
4. 拖拽识别：实现拖拽文件到窗口，自动读取文件内容并生成二维码（例如，拖拽一个.txt文件）。
5. 错误恢复：当 libqrencode 编码失败时，除了弹窗提示，还可以在界面中给出更具体的建议，比如“当前内容在 H 级纠错下最多支持 X 个字符”。

这个基于 Qt/C++ 的二维码生成器项目，虽然功能聚焦，但完整地串联了桌面应用开发的各个环节。从环境配置、第三方库集成、UI 设计、核心逻辑实现，到最后的打包部署，每一步都包含了开发者需要掌握的实用技能和避坑经验。希望这份详细的拆解能帮助你理解其背后的原理，并能动手打造属于自己的版本。

工程源码链接：你可以通过 GitHub - QtQRCodeGenerator 获取完整的、可编译的源代码。仓库中包含了项目文件、配置好的 libqrencode 库（Windows MinGW 版本）以及详细的 README 说明。欢迎 Star、Fork 和提交 Issue。