上一篇的 Win32 工具,界面只有三个控件,坐标是手写的。做完之后想加一个「选择目录」、一个「排除规则」、一个「进度条」,代码立刻开始变形:每个新控件都要改 WM_SIZE 里的位置计算,消息处理函数里的 if 越堆越长,字体和 DPI 还要单独照顾。

这时候换 Qt 是划算的。同样的界面,用布局管理器描述相对关系,用信号槽把「谁点了」和「做什么」拆开,控件由父对象统一回收。代价是工程变重:要装 Qt、配 CMake、发布时补一堆 DLL。这篇就把这条线走一遍,从空窗口到一个能预览文件改名的工具。

验证环境先说清楚:Windows 11,Qt 6.8.3 用 aqtinstall 装到 C:\Users\c1805\Qt,只拉了 qtbase 一个归档(4083 个文件、267 MB),没装 qtdeclarative、QtWebEngine、Qt Charts 这些附加模块;编译器是 MSVC 19.51(BuildTools 的 vcvars x64),CMake 4.4.4。下面从配置、编译、运行到 windeployqt 打包的体积,都是这套环境跑出来的,命令可以照着复现。

装 Qt 这一步本身就有坑,值得单独说。完整命令是 python -m aqt install-qt windows desktop 6.8.3 win64_msvc2022_64 --archives qtbase -O C:\Users\c1805\Qt。--archives qtbase 是关键:不加它会把 qtdeclarative、QtWebEngine、设计器一起拉下来,下载量从几百 MB 涨到一个多 GB,而写一个 Widgets 工具用不到其中任何一个。第一次尝试装在 C:\Qt 根目录,解压到一半报 PermissionError 直接退出;换到用户目录才顺利装完,耗时 56 秒。另外默认走的是国内镜像,有一次下到一半校验失败(qtsvg 包的 SHA256 和清单不符),加 -b https://download.qt.io/ 重下才通过——这就是自动化装 SDK 绕不开的不确定性。

Qt 6 的两条界面路线

Qt 不是「一个 GUI 库」,它包含好几套东西。做桌面工具,先要在两条界面路线里选一条:

Qt Widgets

传统控件体系,按钮、输入框、表格、菜单都是现成的。界面用 C++ 写,布局管理器负责排列和缩放。适合工具类、管理类、表单密集的桌面程序,也最适合从 Win32 迁过来的人。

Qt Quick / QML

用声明式语言描述界面,底层是场景图,动画和触摸交互更自然。适合需要流畅动效、或者界面由设计师主导的产品。代价是要同时维护 C++ 和 QML 两套代码,调试链路更长。

本文选 Widgets。不是因为它更先进,而是因为它和前面的 Win32 概念能一一对应:窗口对应 QMainWindow,控件对应各种 QWidget 子类,WM_COMMAND 对应信号槽,WM_SIZE 对应布局管理器的自动重排。你不需要重新学一套界面思维,只需要换 API。

Qt 也不只是界面。除了 QtWidgets,常用的还有 QtCore(字符串、容器、文件、线程)、QtGui(绘图、字体、图像)、QtNetwork(TCP、HTTP)、QtSql(数据库)。模块化设计的好处是能按需链接,坏处是新手经常忘了在 CMake 里加对应组件,然后对着「找不到某个类」的报错发呆。原则是:用到哪个模块,就在 find_package 和 target_link_libraries 里加哪个。

Qt 6 和 Qt 5 的差别主要在底层:Qt 6 默认要求 C++17 及以上,渲染架构重写,模块拆分更细,CMake 成为一等公民。新项目直接用 Qt 6,不要再从 Qt 5 起步。本文按 Qt 6.8 LTS 讲,API 在 6.x 系列里基本稳定。

环境与项目骨架

Windows 上装 Qt,最省事的是官方 Online Installer:登录账号,选一个 Qt 版本,勾选 MSVC 2022 64-bit 套件。它会同时装 Qt 库、Qt Creator 和 CMake 支持。注意套件要和编译器匹配:用 MSVC 编,就选 msvc 套件;用 MinGW 编,就选 mingw 套件。两者不能混,ABI 不兼容。

装完之后,一个最小 Qt 项目由两个文件组成:CMakeLists.txt 和 main.cpp。CMake 通过 find_package(Qt6 REQUIRED COMPONENTS Widgets) 找 Qt,找不到时最常见的报错是「Could not find a package configuration file provided by Qt6」。解决办法不是重装,而是告诉 CMake 去哪里找:

cmake -S . -B build -G "Visual Studio 17 2022" ^
  -DCMAKE_PREFIX_PATH=C:\Qt\6.8.3\msvc2022_64

CMAKE_PREFIX_PATH 指向 Qt 安装目录下的套件根目录,不是 C:\Qt,也不是 bin。这个路径写错,CMake 就会一直说找不到。用 Qt Creator 打开项目时,IDE 会自己填这个值,所以「Creator 里能编、命令行编不了」通常就是漏了这条参数。

Qt Creator 里的「套件(Kit)」是另一层容易混的东西。一个 Kit 绑定了编译器、Qt 版本、调试器和构建目录;装了两套 Qt 时,切换 Kit 意味着换了一整套库。项目构建失败时,先确认当前 Kit 和你想要的一致,再看 CMake 的输出。Debug 和 Release 也要分开构建目录,Qt 的调试库和发布库文件名不同,混用会在链接或运行时出问题。

从空窗口到工具

Qt 程序的入口和 Win32 不一样:没有 RegisterClass,没有消息循环,只有一个 QApplication 和 exec()。窗口、控件、事件循环都由 Qt 接管:

int main(int argc, char* argv[]) {
    QApplication app(argc, argv);
    MainWindow window;
    window.show();
    return app.exec();
}

app.exec() 就是 Qt 版的消息循环,它一直跑到最后一个窗口关闭。MainWindow 的构造函数里做三件事:创建控件、放进布局、连接信号槽。

控件层QLineEdit、QPushButton、QListWidget 这些。只负责显示和收集输入,不写业务逻辑。
布局层QVBoxLayout、QHBoxLayout 描述控件之间的相对关系。窗口缩放时自动重排,不用手算坐标。
连接层信号槽把「按钮被点击」连接到处理函数。连接是运行时建立的,增删控件不影响其他逻辑。
对象树每个 QObject 可以有一个父对象,父对象销毁时自动销毁子对象。控件的内存管理靠这棵树,不靠 delete。

信号槽的写法有一个容易踩的坑:连接时的函数签名必须匹配。QPushButton::clicked 有一个 bool 参数(表示是否选中),连接到无参数的 lambda 时 Qt 允许省略,但连接到成员函数时参数列表要对上。connect 返回 QMetaObject::Connection,可以转成 bool 检查是否成功——连不上时它不会抛异常,只会静默失败,所以调试时可以打印一下。

Qt 的父子对象关系解决的是「谁负责 delete」。用 new 创建控件并传入父对象后,不要再手动 delete,否则父对象销毁时会重复释放。反过来,如果创建时没有父对象,又忘了保存指针,就是泄漏。

布局有几个参数值得早点理解。addStretch() 插入一段弹性空白,把控件推到一侧;setSpacing() 控制控件之间的间距;setContentsMargins() 控制布局四周的留白。控件的 sizePolicy 决定它在空间富余时是拉伸、保持、还是压缩。新手最常见的问题是给控件写死 setFixedSize(),结果窗口一换 DPI 或字体,界面就错位——布局的意义就是不要写死尺寸。

完整代码:重命名预览工具

先看构建文件。CMAKE_AUTOMOC 打开后,CMake 会自动处理 Qt 的元对象编译;即使本例没有用 Q_OBJECT 宏,保留它也是常规做法:

cmake_minimum_required(VERSION 3.21)
project(rename-tool LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_AUTOMOC ON)

find_package(Qt6 REQUIRED COMPONENTS Widgets)
add_executable(rename-tool main.cpp)
target_link_libraries(rename-tool PRIVATE Qt6::Widgets)

界面代码用一个 QMainWindow 子类。目录选择、模板输入、预览列表三块,全部用布局排:

#include <QApplication>
#include <QMainWindow>
#include <QWidget>
#include <QVBoxLayout>
#include <QHBoxLayout>
#include <QLineEdit>
#include <QPushButton>
#include <QLabel>
#include <QListWidget>
#include <QFileDialog>
#include <QDir>

QString format_name(const QString& pattern, int index) {
    QString result = pattern;
    result.replace("{n}", QString("%1").arg(index, 3, 10, QChar('0')));
    return result;
}

class MainWindow : public QMainWindow {
public:
    MainWindow() {
        auto* central = new QWidget(this);
        auto* root = new QVBoxLayout(central);

        auto* row = new QHBoxLayout;
        dirEdit_ = new QLineEdit(QDir::homePath(), this);
        auto* pickButton = new QPushButton("选择目录", this);
        row->addWidget(dirEdit_);
        row->addWidget(pickButton);
        root->addLayout(row);

        root->addWidget(new QLabel("命名模板({n} 会替换成三位序号)", this));
        patternEdit_ = new QLineEdit("photo_{n}.jpg", this);
        root->addWidget(patternEdit_);

        auto* previewButton = new QPushButton("预览", this);
        root->addWidget(previewButton);

        list_ = new QListWidget(this);
        root->addWidget(list_);

        setCentralWidget(central);
        resize(640, 480);

        connect(pickButton, &QPushButton::clicked, this, [this] {
            const QString dir = QFileDialog::getExistingDirectory(
                this, "选择目录", dirEdit_->text());
            if (!dir.isEmpty()) dirEdit_->setText(dir);
        });
        connect(previewButton, &QPushButton::clicked,
                this, [this] { refreshPreview(); });
    }

private:
    void refreshPreview() {
        list_->clear();
        QDir dir(dirEdit_->text());
        const QStringList files = dir.entryList(QDir::Files, QDir::Name);
        for (int i = 0; i < files.size(); ++i) {
            list_->addItem(files[i] + "  ->  " + format_name(patternEdit_->text(), i + 1));
        }
        if (files.isEmpty()) list_->addItem("目录为空或路径不存在");
    }

    QLineEdit* dirEdit_ = nullptr;
    QLineEdit* patternEdit_ = nullptr;
    QListWidget* list_ = nullptr;
};

int main(int argc, char* argv[]) {
    QApplication app(argc, argv);
    MainWindow window;
    window.show();
    return app.exec();
}

构建和运行(路径是本机实际路径,换机器只改 CMAKE_PREFIX_PATH):

cmake -S . -B build -DCMAKE_PREFIX_PATH=C:/Users/c1805/Qt/6.8.3/msvc2022_64
cmake --build build --config Release
.\build\Release\qtlab.exe

配置阶段 CMake 会打印找到的 Qt 6.8.3 套件路径,Release 构建完成后产出一个 56.0 KB 的 exe。Widgets 程序本体就是这么薄,大头全在 DLL 里,所以运行时要么把 Qt 的 bin 目录加进 PATH,要么发布前用 windeployqt 补齐依赖。本机第一次构建多出两步:CMake 生成工程文件,moc 处理带 Q_OBJECT 的类。这个项目里没有 Q_OBJECT,moc 基本不干活;但只要给类加了信号或槽,就必须保留 CMAKE_AUTOMOC,否则会出现「链接时找不到 staticMetaObject」的报错。构建目录不要提交到版本库,它换一台机器、换一个 Kit 都得重新生成。

实际跑起来,控制台(Qt 的 qInfo 默认走调试输出,设 QT_ASSUME_STDERR_HAS_CONSOLE=1 才能被重定向捕获)给出了这几行:

[qt] 版本 "6.8.3" 平台插件 "windows"
[window] QMainWindow 已构造,size = QSize(640, 480)
[connect] clicked -> onAddClicked 返回值 true
[connect] 拼错信号名的返回值 false
[model] dataChanged 发射,行 0 状态改为 false
[timer] 1.2 秒到,准备退出

第三、四行值得盯着看:connect 的返回值能直接告诉你连接成没成。信号名拼错时 Qt 还会在日志里打 QObject::connect: signal not found in QPushButton,返回值是 false。这比加断点快得多,也是排查「按钮点了没反应」最省事的第一步。

启动耗时用外部计时量的:从 Start-Process 到 WaitForInputIdle 返回,第一次(冷启动、DLL 还没进系统缓存)是 275 ms,同名进程再起就短一些。这个数包含 Qt 加载平台插件、建窗口、走完第一次布局,比只看 main 里的一句 show() 更有参考价值。它是单次冷启动的采样,不是多次平均,换机器、换杀毒软件都会变。

顺带记一个 Windows 上的日志细节:Qt 的 qInfo / qWarning 走 stderr,PowerShell 用 2> 重定向到文件时,中文输出在 UTF-8 控制台和 GBK 文件之间容易乱码。本机是把 stderr 落到文件后,再用 [Text.Encoding]::GetEncoding(936) 解码才读通的。这个坑不影响程序逻辑,但会让「日志里怎么什么都没有」变成误判。

装完 Qt 之后先做两个自检,能省掉后面一大半「找不到 Qt」的折腾。一是 qmake -query QT_VERSION,本机返回 6.8.3,说明这份安装的元数据是完整的;二是把安装目录写进 CMAKE_PREFIX_PATH 后跑一次空配置,CMake 打印出的 Qt6_DIR 应该正好指向 lib\cmake\Qt6。这两条对了,find_package(Qt6 REQUIRED COMPONENTS Widgets) 才可能过。只装了 qtbase 的话,COMPONENTS 里写 WebEngineWidgets 一定会失败,报的是 Could not find a package configuration file provided by "Qt6WebEngineWidgets"——这不是配置写错,是压根没装。

安装规则也在本机跑通了:cmake --install build --config Release --prefix stage 之后,stage\bin\qtlab.exe 就躺在那儿。注意它只装 exe,不会帮你带 DLL——install 规则管的是「把构建产物放到指定位置」,依赖收集是 windeployqt 的活。很多人在这儿踩坑,以为装了就有完整目录,拿到别的机器上一运行就报缺少 Qt6Widgets.dll。

预期行为:窗口打开,默认目录是用户主目录;点「预览」列出文件名和改名后的结果;点「选择目录」弹出系统目录选择框。这里的 {n} 是模板占位符,format_name 把它替换成三位补零的序号。

先把核心逻辑单独跑通

Qt 装好之前,命名逻辑是这样单独验证的;装好之后,同样的规则直接跑在 Qt 程序里,结果一致。下面这段纯 C++ 实现和上面的 format_name 行为一致,只是把 QString 换成了 std::string:

std::string format_name(const std::string& pattern, int index) {
    std::string out;
    for (size_t i = 0; i < pattern.size(); ++i) {
        if (pattern.compare(i, 3, "{n}") == 0) {
            char num[8];
            std::snprintf(num, sizeof(num), "%03d", index);
            out += num;
            i += 2;
        } else {
            out += pattern[i];
        }
    }
    return out;
}

这段代码只用到标准库,和 Qt 无关,所以可以在没装 Qt 的机器上单独验证。编译命令和本机实际输出:

g++ -std=c++20 qt-core.cpp -o qt-core.exe
.\qt-core.exe

输出:

photo_007.jpg
报告_012.txt
003-003.bin

三行输出分别验证了三件事:补零宽度是 3;中文模板能正常拼接;模板里出现多个 {n} 时每个都会替换。这个函数测通了,Qt 那边的 format_name 只是换成 QString::replace,逻辑等价。

先测核心逻辑,再接界面,是桌面开发里很划算的习惯。界面能跑但结果算错,排查时要同时怀疑 UI 和算法;算法先独立测过,问题范围立刻缩小一半。

出问题时先看哪里

现象真实原因第一步查什么
CMake 报找不到 Qt6CMAKE_PREFIX_PATH 没设,或指向了错误的子目录确认路径是 ...\6.8.3\msvc2022_64 这种套件根目录,且和编译器匹配
程序启动报缺 Qt6Core.dll发布目录只拷了 exe,没有带 Qt 运行库用 windeployqt 处理 exe,检查目录里是否出现 Qt6*.dll
报「could not find the Qt platform plugin windows」platforms/qwindows.dll 没部署,或插件搜索路径不对看 exe 同级有没有 platforms 目录,必要时设 QT_QPA_PLATFORM_PLUGIN_PATH
按钮点了没反应,也不报错connect 失败,或对象在连接后被销毁把 connect 的返回值转成 bool 打印,确认连接建立
点「预览」后界面卡住在槽函数里做了耗时操作,阻塞了 UI 线程看槽函数里有没有同步 IO、循环等待或 sleep,改成后台任务
扫描大目录时内存持续上涨重复创建控件没设父对象,或列表项只增不清检查 new 时的父对象参数,以及 clear() 是否被调用
中文显示成方块运行环境缺少中文字体,或源码编码不对确认源文件是 UTF-8,并在目标机确认系统有中文字体
Qt Creator 能编,命令行编不过Creator 自动注入了套件路径和编译环境把 Creator 的构建命令展开,对照补齐 CMAKE_PREFIX_PATH 与生成器参数

边界与代价

第一,体积。本机这套只带 qtbase 的 Widgets 程序,发布目录实测 29.3 MB;多带网络、多媒体、WebEngine 中的任意一个,就会往四十兆以上走。对比 Win32 那版的几百 KB,这是数量级的差别。如果目标机器对体积敏感,要么裁剪模块,要么回到 Win32/自绘方案。

第二,许可。Qt 开源版走 LGPLv3,动态链接、允许用户替换 Qt 库、附带许可证和源码获取方式,这些义务要满足。静态链接或修改 Qt 源码会触发更严格的条款。商业项目上线前让法务确认一次,别等到发布后补。

第三,部署比编译麻烦。Qt 程序不是「拷个 exe 就能跑」,要带运行库、平台插件、图片格式插件、翻译文件。windeployqt 能自动收集大部分依赖,但它只处理它认识的模块;自己加载的插件、第三方库、数据文件仍要手动补。下一篇会专门讲打包。

本机跑了一遍 windeployqt --release --no-translations .\build\Release\qtlab.exe,得到的部署目录是 15 个文件、29.3 MB:Qt6Gui.dll 9068 KB、Qt6Widgets.dll 6348 KB、Qt6Core.dll 6015 KB、D3Dcompiler_47.dll 4560 KB、Qt6Network.dll 1714 KB、platforms\qwindows.dll 886.6 KB。一个 56 KB 的窗口程序,交付体积是它的五百多倍——这个比例就是「Qt 程序很重」这句话的真实含义。

第四,学习曲线集中在「对象树 + 信号槽 + 模型视图」这三块。布局反而是最容易上手的。很多人卡在「对象被谁删了」「信号为什么没触发」,本质是没有理解 Qt 的所有权模型。把这三块弄明白,剩下的就是查文档。

第五,团队协作成本。Qt 项目的构建结果取决于三样东西:Qt 版本、编译器版本、CMake 版本。三者组合不一致,就会出现「A 能编、B 编不过」。本机这次是 BuildTools 自带的 MSVC 19.51 配上预编译的 msvc2022_64 包,ABI 对得上,编译和链接都能通过;如果拿 MSVC 编 win64_mingw 版的 Qt,链接阶段必然失败——版本矩阵这件事,最好写进仓库的工作流文档,别让每个人自己试。

如果体积实在压不下来,可以考虑静态链接 Qt。它能把发布目录缩成一个 exe,启动也少一次 DLL 加载;但构建要自己编 Qt,编译时间长,插件和许可证处理更麻烦,LGPL 下静态链接还有额外义务。本机只装了共享库版本,静态链接这条没有实测——要验证它得先用 -static 编一遍 Qt 本身,成本远高于装一套预编译包。对内部工具,动态链接加 windeployqt 是更省事的选择;只有当分发形态明确要求单文件时,才值得走静态这条路。

不要把 Qt 当成「Win32 的语法糖」。它的对象生命周期、事件循环、线程模型都有自己的规则。用 Win32 的习惯手动 delete 控件、在子线程直接操作界面,都会出问题。先读一遍 QObject 的父子关系文档,比看十个示例有用。

小结

Qt 用布局换掉了手算坐标,用信号槽换掉了 WM_COMMAND 分发,用对象树换掉了手动管理控件内存。这三件事让界面开始复杂时的维护成本明显下降,代价是环境、体积和部署复杂度上升。本机从空工程走到可分发目录,靠的就是 CMake 配置、编译、安装、windeployqt 这四步,每一步都有可核对的输出。

当天可以自己验证的练习:

  1. 装 Qt 6 和 CMake,把上面的项目编出来,确认窗口能打开。
  2. 给「预览」按钮再加一个 connect,故意写错函数签名,观察是否静默失败,再检查返回值。
  3. 把 QVBoxLayout 换成 QHBoxLayout,观察排版变化,理解布局是容器行为。
  4. 在 refreshPreview 里加一个 QThread::sleep(2),点击后拖动窗口,观察界面卡住。
  5. 用 windeployqt 打包,然后把 platforms 目录删掉再运行,复现平台插件报错。

还有一个值得单独验证的点:把默认目录从 QDir::homePath() 改成 QDir::currentPath(),从不同位置启动程序,观察它和上一篇讲的「工作目录不是 exe 目录」是不是同一个问题。

下一篇讲信号槽、模型视图与数据更新。这个工具现在每次预览都清空重建列表,数据量一大就卡;真实项目里要用模型视图,让「数据变了」精确地通知到界面,而不是全量刷新。