Qt 总结笔记

发表于 2023-07-22 更新于 2025-03-24 分类于 code 本文字数： 3.9k 阅读时长 ≈ 14 分钟

1 Qt 语法

Qt 信号与槽使用方法最完整总结

2 Qt 学习资料

3 Qt 程序发布的流程

Qt Creator 开发程序
选择 release 编译后，在源码文件夹之外会生成构建的文件夹，带有 - Release 尾缀，在这个目录下拷贝程序的 exe 二进制文件到一个新建的文件夹中。
运行 windeployqt 工具打包动态链接文件：windeployqt program_name.exe。确保提前添加环境变量 PATH：C:\Qt\qt6release\bin，否则找不到 windeployqt 程序。P.S. 使用 vs cl 终端运行 windeployqt 会同时拷贝 vc_redist.x64.exe 安装包（Microsoft Visual C++ 2015-2022 Redistributable (x64) - 14.36.32532，可以解决目标系统缺少 dll 动态链接库的报错），使用普通的终端运行 windeployqt 则不会拷贝这个文件（Warning: Cannot find Visual Studio installation directory, VCINSTALLDIR is not set.），但实际上可以手动拷贝 dll 动态链接库文件到程序根目录，可免去用户再次运行安装运行库。
NSIS 打包生成安装包：创建快捷方式、创建卸载程序、界面美化（模仿网易云音乐安装包）、判断是否正在运行、判断并安装 VC 运行库。

3.1 单文件封包流程

除了静态编译可以单文件的打包，动态链接编译开发也可以实现，这个需要使用三方封包工具了，一般都是使用 Enigma Virtual Box 进行单文件的打包。

单文件打包流程：

新建文件夹，拷贝 qt 程序 exe，运行 windeployqt.exe 打包动态链接文件，拷贝额外的 MS VC++ DLL 文件
打开 Enigma Virtual Box，选择打包的程序
选择好打包程序后会自动生成一个打包后的程序名
在增加文件选项里面选择增加文件夹 [递归] ，把前面创建存放文件的文件夹包含进去
在文件选项选择压缩文件
执行封包

缺点：使用 Enigma Virtual Box 打包的单文件，有可能会被杀毒软件识别为病毒，比如 Windows Defender。

4 Qt 下载

资源名称	官方源下载地址	清华镜像源下载地址
Qt 资源总站	点击跳转	点击跳转
Qt 源代码	点击跳转	点击跳转
Qt Creator	点击跳转	点击跳转
Qt Linguist	点击跳转	点击跳转

5 Qt Creator 的总结

5.1 安装 Qt Creator 提示要求联网登录帐号

断网再打开 Qt Creator 的安装包，等跳过检测联网帐号的界面后就可以启用网络继续安装。

5.2 修改模板文件以便新建工程时默认支持 C++20

使用程序完成批量修改：modify_qt_creator_template_files_to_support_c++20.bat

cmake
qmake

将以下文件中的 set(CMAKE_CXX_STANDARD 17) 修改为 set(CMAKE_CXX_STANDARD 20)

qtcreator-16.0.0\share\qtcreator\templates\wizards\projects\consoleapp\CMakeLists.txt
qtcreator-16.0.0\share\qtcreator\templates\wizards\projects\cpplibrary\CMakeLists.txt
qtcreator-16.0.0\share\qtcreator\templates\wizards\projects\plaincpp\CMakeLists.txt
qtcreator-16.0.0\share\qtcreator\templates\wizards\projects\qtquickapplication_compat\CMakeLists.txt
qtcreator-16.0.0\share\qtcreator\templates\wizards\projects\qtwidgetsapplication\CMakeLists.txt

将以下文件中的 CONFIG += c++17 修改为 CONFIG += c++20

qtcreator-16.0.0\share\qtcreator\templates\wizards\projects\consoleapp\file.pro
qtcreator-16.0.0\share\qtcreator\templates\wizards\projects\cpplibrary\project.pro
qtcreator-16.0.0\share\qtcreator\templates\wizards\projects\plaincpp\file.pro
qtcreator-16.0.0\share\qtcreator\templates\wizards\projects\qtwidgetsapplication\project.pro

6 Qt 国际化多语言的总结

QT 官方多语言编程 wiki 参考：How to create a multi language application

创建工程文件时，勾选国际化选项。
打开 CMakeLists.txt 文件，修改 ${TS_FILES} 对应的文件和手动生成需要的 ts 文件，找到 if(${QT_VERSION_MAJOR} GREATER_EQUAL 6) 语句，在该 if 语句内添加如下内容，其中 untitled 为项目名称。如果还需要创建对应资源文件的话，就创建 languages.qrc 并有 qt 资源编辑器打开编辑。

qt_create_translation(QM_FILES ${CMAKE_SOURCE_DIR} ${TS_FILES})
qt_add_executable(untitled
    MANUAL_FINALIZATION
    ${PROJECT_SOURCES}
    ${TS_FILES}
    ${QM_FILES}
)

编辑 ui 文件，编辑程序界面文本。
构建工程，ts 文件会自动生成对应的文本（无需使用 QT Creator 的工具 -> 外部 ->Linguist->Update/Release Translations (lupate)，这个工具运行会报错）

6.1 创建工程提示找不到合适的套件

问题：安装 Qt Creator 之后，在创建工程提示 No suitable kits found.

解决：点击管理，手动设置构建套件 kit 的 qt 版本，这是通过选择 qmake.exe 或者 qmake6.exe 的路径确认。（不用重装，网上的教程都是重装或者安装在线版本包，但直接重装是无效）。

6.2 旧项目的套件配置文件中的 CL 编译器路径不正确

原因：更新 MSVC CL 后，老版本编译器就被删除了，旧项目的套件配置文件中的 CL 编译器路径仍然是老版本的路径，导致路径错误无法识别最新版本的编译器。

解决方法：删除项目父路径中生成的构建配置文件夹，例如 build-untitled-x64-Release，然后重新构建新的配置文件夹。

7 Qt 源码编译

7.1 个人编译使用的模块

以下是我个人使用到的模块（按编译顺序列出）

qtbase（基础库）
qtshadertools（编译 qtdeclarative 所需的依赖库）
qtdeclarative（qt quick 和 QML）
qttools（CMakeLists 文件中指明要 Qt Linguist 包，因此即使在 qt creator 中没用上「工具」->「外部」->「Linguist」也要编译）
qtsvg（FluentUI 库所需）
qt5compat（FluentUI 库所需）
~~qttranslation~~（如果不编译这个库，运行 windeployqt 会出现警告：Warning: Translations will not be available due to the following error. Cannot open C:/Qt/qt6release/translations/catalogs.json。但这个错误实际不影响程序的翻译状态，可以不编译）

7.2 环境配置和编译步骤

环境变量：一定要确保系统 PATH 环境变量含有 CMake 和 Ninja 路径。关于如何详细设置，可以参见 MSVC CL 编译器的安装和环境设置。

注意不能使用 ninja 直接构建源码，会报错：build.ninja not found。构建是使用 CMake。

编译步骤：

将源码解压到分区的根目录下，例如：G:\qtbase-everywhere-src-6.8.2
在源码文件夹外新建一个文件夹，如 qtbasebuild，拷贝该编译脚本进文件夹，打开 cmd 窗口，执行该脚本（不建议直接双击运行编译脚本，因为脚本编译出错或者执行完毕都会关闭窗口，这样无法得知编译详情）。
编译完成后添加环境变量 PATH 配置：C:\Qt\qt6release\bin

7.3 单模块逐个编译的 BAT 脚本

附加编译子模块的方式：运行 Qt 安装路径下的 /bin/qt-configure-module.bat + 附件模块源码解压路径。

一般普通开发编译 release 版本即可，debug 版本是是编译用来开发调试 qt 源码的。

7.3.1 编译 release 版本

7.3.1.1 编译 qtbase (release)

@chcp 65001>nul
@echo off
CALL "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvarsall.bat" x64
..\qtbase-everywhere-src-6.8.2\configure.bat -prefix C:\Qt\qt6release -c++std c++20 -release -optimize-size -shared && cmake --build . --parallel && cmake --install .

7.3.1.2 附加编译其他子模块（release）

@chcp 65001>nul
@echo off
CALL "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvarsall.bat" x64
C:\Qt\qt6release\bin\qt-configure-module.bat G:\qtshadertools-everywhere-src-6.8.2 && cmake --build . --parallel && cmake --install .

7.3.2 编译 debug 版本

7.3.2.1 编译 qtbase (debug)

@chcp 65001>nul
@echo off
CALL "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvarsall.bat" x64
..\qtbase-everywhere-src-6.8.2\configure.bat -prefix C:\Qt\qt6debug -c++std c++20 -debug -shared && cmake --build . --parallel && cmake --install .

7.3.2.2 附加编译其他子模块（debug）

@chcp 65001>nul
@echo off
CALL "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvarsall.bat" x64
C:\Qt\qt6debug\bin\qt-configure-module.bat ..\qtshadertools-everywhere-src-6.8.2 && cmake --build . --parallel && cmake --install .

7.4 编译遇到的坑

7.4.1 系统 PATH 环境变量含有 CL 路径，但终端手动编译时依旧报错

问题：系统 PATH 环境变量含有 CL 路径，直接输入 cl 可以查询到该命令。但终端手动编译时依旧出错，cmake 等操作无法正常运行。

解决方式：需要在 MSVC Cl 初始化环境的情况下编译。不能使用普通终端运行，虽然系统 PATH 有添加可识别 CL 命令，但是 CL 相关环境变量只能通过 vcvarsall.bat 设置，例如 vcvarsall.bat x64。

7.4.2 无法写入源文件更新的清单

报错信息：mt.exe : general error c101008d: Failed to write the updated manifest to the resource of file

解决方法：多线程编译偶尔引起的现象，重新运行编译脚本命令即可。（个人见解：多线程编译引起资源阻塞，导致写入失败）

7.4.3 找不到 qtshadertools 'qsb' 工具

报错信息：Note: Qt Quick modules not built due to not finding the qtshadertools 'qsb' tool.

解决方法：qtdeclarative 模块依赖于 qtshadertools 模块，需要先编译安装好 qtshadertools，之后再编译安装 qtdeclarative。

7.4.4 optimize_size 选项导致编译中断

报错信息：

ERROR: Feature "optimize_size": Forcing to "ON" breaks its condition:
    NOT QT_FEATURE_debug OR QT_FEATURE_debug_and_release
Condition values dump:
    QT_FEATURE_debug = "ON"
    QT_FEATURE_debug_and_release = "OFF"


CMake Error at cmake/QtBuildInformation.cmake:194 (message):
  Check the configuration messages for an error that has occurred.
Call Stack (most recent call first):
  cmake/QtBuildInformation.cmake:24 (qt_configure_print_summary)
  cmake/QtBuildInternals/QtBuildInternalsConfig.cmake:548 (qt_print_feature_summary)
  CMakeLists.txt:198 (qt_build_repo_end)


-- Configuring incomplete, errors occurred!
CMake Error at G:/qtbase-everywhere-src-6.8.2/cmake/QtProcessConfigureArgs.cmake:995 (message):
  CMake exited with code 1.

解决方法：这是因为在 64 位的系统上选择 x32 的编译器引起的错误。根据自己的平台选择对应的编译器，例如，MSVC CL 编译器的 x64 环境，否则启用 optimize_size 选项有相关报错信息。当然，不启用该选项的话，可正常编译，但得不偿失。

7.4.5 链接 lib 文件出现错误 LNK2019

问题：链接 lib 文件报错，error LNK2019: 无法解析的外部符号。

-- Configuring done (10.5s)
-- Generating done (2.6s)
-- Build files have been written to: G:/qtdeclarative
[1569/4804] Linking CXX shared library bin\Qt6QmlXmlListModeld.dll
FAILED: bin/Qt6QmlXmlListModeld.dll lib/Qt6QmlXmlListModeld.lib
cmd.exe /C "cd . && "C:\Program Files\CMake\bin\cmake.exe" -E vs_link_dll --intdir=src\qmlxmllistmodel\CMakeFiles\QmlXmlListModel.dir\Debug --rc="C:\PROGRA~2\Windows Kits\10\bin\10.0.22621.0\x64\rc.exe" --mt="C:\PROGRA~2\Windows Kits\10\bin\10.0.22621.0\x64\mt.exe" --manifests  -- "C:\PROGRA~2\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\14.36.32532\bin\Hostx64\x64\link.exe" /nologo src\qmlxmllistmodel\CMakeFiles\QmlXmlListModel.dir\Debug\QmlXmlListModel_autogen\mocs_compilation_Debug.cpp.obj src\qmlxmllistmodel\CMakeFiles\QmlXmlListModel.dir\Debug\cmake_pch.cxx.obj src\qmlxmllistmodel\CMakeFiles\QmlXmlListModel.dir\Debug\Debug\QmlXmlListModel_resource.rc.res src\qmlxmllistmodel\CMakeFiles\QmlXmlListModel.dir\Debug\qqmlxmllistmodel.cpp.obj src\qmlxmllistmodel\CMakeFiles\QmlXmlListModel.dir\Debug\qmlxmllistmodel_qmltyperegistrations.cpp.obj src\qmlxmllistmodel\CMakeFiles\QmlXmlListModel.dir\Debug.rcc\qrc_qmake_QtQml_XmlListModel.cpp.obj  /out:bin\Qt6QmlXmlListModeld.dll /implib:lib\Qt6QmlXmlListModeld.lib /pdb:bin\Qt6QmlXmlListModeld.pdb /dll /version:6.5 /machine:x64 /debug  -DYNAMICBASE -NXCOMPAT -LARGEADDRESSAWARE  lib\Qt6QmlModelsd.lib  lib\Qt6Qmld.lib  C:\Qt\qt6\lib\Qt6Network.lib  C:\Qt\qt6\lib\Qt6Core.lib  mpr.lib  userenv.lib  ws2_32.lib  shell32.lib  kernel32.lib user32.lib gdi32.lib winspool.lib shell32.lib ole32.lib oleaut32.lib uuid.lib comdlg32.lib advapi32.lib  && cd ."
LINK: command "C:\PROGRA~2\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\14.36.32532\bin\Hostx64\x64\link.exe /nologo src\qmlxmllistmodel\CMakeFiles\QmlXmlListModel.dir\Debug\QmlXmlListModel_autogen\mocs_compilation_Debug.cpp.obj src\qmlxmllistmodel\CMakeFiles\QmlXmlListModel.dir\Debug\cmake_pch.cxx.obj src\qmlxmllistmodel\CMakeFiles\QmlXmlListModel.dir\Debug\Debug\QmlXmlListModel_resource.rc.res src\qmlxmllistmodel\CMakeFiles\QmlXmlListModel.dir\Debug\qqmlxmllistmodel.cpp.obj src\qmlxmllistmodel\CMakeFiles\QmlXmlListModel.dir\Debug\qmlxmllistmodel_qmltyperegistrations.cpp.obj src\qmlxmllistmodel\CMakeFiles\QmlXmlListModel.dir\Debug.rcc\qrc_qmake_QtQml_XmlListModel.cpp.obj /out:bin\Qt6QmlXmlListModeld.dll /implib:lib\Qt6QmlXmlListModeld.lib /pdb:bin\Qt6QmlXmlListModeld.pdb /dll /version:6.5 /machine:x64 /debug -DYNAMICBASE -NXCOMPAT -LARGEADDRESSAWARE lib\Qt6QmlModelsd.lib lib\Qt6Qmld.lib C:\Qt\qt6\lib\Qt6Network.lib C:\Qt\qt6\lib\Qt6Core.lib mpr.lib userenv.lib ws2_32.lib shell32.lib kernel32.lib user32.lib gdi32.lib winspool.lib shell32.lib ole32.lib oleaut32.lib uuid.lib comdlg32.lib advapi32.lib /MANIFEST /MANIFESTFILE:bin\Qt6QmlXmlListModeld.dll.manifest" failed (exit code 1120) with the following output:
正在创建库 lib\Qt6QmlXmlListModeld.lib 和对象 lib\Qt6QmlXmlListModeld.exp
qqmlxmllistmodel.cpp.obj : error LNK2019: 无法解析的外部符号 "__declspec(dllimport) public: __cdecl QtPrivate::ResultIteratorBase::~ResultIteratorBase(void)" (_imp??1ResultIteratorBase@QtPrivate@@QEAA@XZ)，函数 "public: struct QQmlXmlListModelQueryResult const & __cdecl QFutureInterface<struct QQmlXmlListModelQueryResult>::resultReference(int)const " (?resultReference@?$QFutureInterface@UQQmlXmlListModelQueryResult@@@@QEBAAEBUQQmlXmlListModelQueryResult@@H@Z) 中引用了该符号
bin\Qt6QmlXmlListModeld.dll : fatal error LNK1120: 1 个无法解析的外部命令
[1598/4804] Automatic MOC for target Quick
ninja: build stopped: subcommand failed.

解决方式：这是启用 debug-and-release 编译源码导致的，debug 和 release 同时编译易出问题，因此建议分开编译。

7.4.6 编译的字符报错或者其他问题

问题：编译可能提示找不到路径或者字符报错等其他问题，可能是由于中文路径引起。

解决方式：路径中不要含有中文字符，可以在磁盘根目录下操作，这样可保证路径总字符不会很多。

7.4.7 终端编译报错：The input line is too long

报错信息：

1 2	The input line is too long. The syntax of the command is incorrect.

问题原因：单个终端实例多次运行命令，导致累积长度超过 8191 个字符，触发了命令行长度限制报错。该现象常见于终端窗口里面多次运行编译命令引起，不知道为啥多次会累积计算这个长度。例如我从 qtbase->qt5compat 编译总共 6 个模块，在编译第五个 qtsvg 模块时，在尝试执行 BAT 编译脚本就会出现该报错。

解决方法：直接关闭终端，重新在该路径上创建终端窗口实例。

7.5 Qt 各模块的介绍及其依赖项：

Module	Required submodules	Development packages required	Description
qtbase			Qt core, start with this.
qtimageformats		libmng-dev	Support for loading various extra image formats TIFF, MNG, WebP
qtsvg			Support for SVG vector graphics
qtshadertools			Tools for the cross-platform Qt shader pipeline
qttools	qtdeclarative	QDoc requires clang to be installed (See section about documentation above): clang-11 libclang-11-dev libclang-common-11-dev	Various Qt tools: QtAssistant Qt Designer Qt Linguist QDoc etc
qtserialbus			Serial bus (CAN bus, ModBus) support
qtserialport	qtserialbus		Serial port support
qtlocation	qtserialport		Positioning (GPS) and location (Map) services
qtdeclarative	qtshadertools		Qt Quick / QML
qtmultimedia	qtdeclarative	For ffmpeg backend (prefered backend since 6.5): ffmpeg libavcodec-dev libavdevice-dev libavfilter-dev libavformat-dev libavutil-dev libswresample-dev libswscale-dev For gstreamer backend: libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev gstreamer1.0-plugins-base gstreamer1.0-plugins-good gstreamer1.0-plugins-ugly gstreamer1.0-plugins-bad libgstreamer-plugins-bad1.0-dev gstreamer1.0-pulseaudio gstreamer1.0-tools gstreamer1.0-alsa For pulseaudio support: pulseaudio libpulse-dev For plain ALSA: libasound2-dev	Multimedia (audio/video) support Audio play, record Video play Video input, capture
qt3d
qtquick3d			A high-level API for creating 3D content and 3D user interfaces based on Qt Quick
qtquick3dphysics			A physics engine for use with Qt Quick 3D
qtdatavis3d
qtsensors	qtmultimedia		Support for various device sensors
qtnetworkauth			Network authentication protocol support (OAuth)
qtconnectivity		bluez libbluetooth-dev	Bluetooth and NFC connectivity support
qtwebsockets	qtdeclarative		Websockets support
qtcharts	qtdeclarative		Charting controls
qtwayland		libwayland-dev	Wayland support
qtvirtualkeyboard	qtsvg		Provides on-screen keyboard
qtwebengine	qtdeclarative	flex bison gperf libre2-dev libnss3-dev nodejs libdrm-dev libxdamage-dev libsnappy-dev	WebEngine.
qtgrpc			Support for gRPC
qthttpserver			Qt HTTP Server
qtspeech			Text To Speech with Flite
qt5compat			Unsupported Qt 5 compatibility code.

8 Qt 的许可协议和费用问题

使用 LGPL 协议开发闭源程序，若使用动态链接的形式，可以以任何形式发布应用程序，只需声明使用 Qt 开发即可。

9 参考资料

[1] Building Qt 6.5 submodules[EB/OL]. https://www.tal.org/tutorials/building-qt-65-sub-modules.
[2] 用 VS Code 搞 Qt6：编译附加模块 [EB/OL]. https://www.cnblogs.com/tcjiaan/p/16575655.html.
[3] Building Qt 6 from Git[EB/OL]. https://wiki.qt.io/Building_Qt_6_from_Git.
[4] Obligations of the GPL and LGPL[EB/OL]. https://www.qt.io/licensing/open-source-lgpl-obligations.
[5] Qt 收费吗？[EB/OL]. https://blog.csdn.net/csyounth/article/details/7347182.
[6] Qt 的开源版本与商业版区别及 LGPL 与闭源程序 [EB/OL]. https://blog.csdn.net/heli200482128/article/details/79305245.
[7] Qt5 怎么最小化编译，只编译 qtbase [EB/OL]. https://blog.csdn.net/jhkwei/article/details/107949403.
[8] Qt 5.15.0 编译指南 [EB/OL]. https://blog.csdn.net/zxjohnson/article/details/106621457.
[9] 在 Mac 编译成功运行 qt5.15 源码：debug 和 release 版本 [EB/OL]. https://xmuli.tech/posts/8b05b275/.
[10] 愿编程不再乱码 (含 Qt)- 根因深究 [EB/OL]. https://ifmet.cn/posts/c0862e62/.
[11] QT error: LNK2019: 无法解析的外部符号 “__declspec (dllimport) public:[EB/OL]. https://blog.csdn.net/lifuran156/article/details/118935649.
[12] error LNK2019: 无法解析的外部符号”__declspec (dllimport)[EB/OL]. https://www.cnblogs.com/lihaozy/archive/2012/07/05/2577512.html.
[13] 配置 Qt 新建工程时默认支持 C++14 或 C++17 [EB/OL]. https://blog.csdn.net/no_say_you_know/article/details/121924999.
[14] 首次安装 Qt 后，创建项目时出现 “No valid kits found” 的解决办法 [EB/OL]. https://codeantenna.com/a/Mc08ZG5tEW.
[15] 教你使用 windeployqt 工具来进行 Qt 的打包发布 [EB/OL]. https://blog.csdn.net/sinat_36264666/article/details/73305712.
[16] QT5 实现语言国际化（中英文界面动态切换，超详细）[EB/OL]. https://blog.csdn.net/m0_49047167/article/details/108442111.
[17] Qt 项目 (CMake) 设置国际化支持 [EB/OL]. https://blog.csdn.net/qq_33154343/article/details/114439385.
[18] QT 使用 Enigma Virtual Box 打包 exe [EB/OL]. https://blog.csdn.net/qq_40994692/article/details/113880198.
[19] Qt 实现单个 EXE 文件（绿色运行版） Enigma Virtual Box [EB/OL]. https://www.cnblogs.com/ybqjymy/p/13926394.html.
[20] Virus detection by Windows Defender in boxed exe[EB/OL]. http://forum.enigmaprotector.com/viewtopic.php?t=14841.