简介这是一份Qt窗口程序入门示例面向刚接触Qt Widgets的开发者用于演示从零搭建多窗口GUI应用。压缩包共9个文件大小仅5KB包含3个cpp源文件、2个h头文件、2个ui界面定义文件以及pro工程文件和user配置涵盖源码、界面和工程配置可直接用Qt Creator打开编译。示例以“2Wdiget”双窗口为主展示登录对话框与主窗口的跳转逻辑覆盖QWidget/QMainWindow派生、界面布局、信号槽触发登录验证以及事件循环启动时机同时演示了如何管理两个独立窗口的显示与关闭并让读者直观理解ui文件与cpp头文件的分工方式。已有776人学习适合课程设计、毕业设计和自学练手也可作为后续加入数据库、网络通信等复杂功能的启动模板。 拿到一个叫Qt窗口程序示例.rar的文件大多数人第一反应是解压、双击 exe然后面对两种结果要么窗口压根没弹出来要么弹一个no Qt platform plugin could be initialized的亮黄色窗口顺带还提示你 reinstalling the application。这个压缩包看似只是一个小示例背后涉及的环节却足够劝退一批刚入门的 Qt 学习者开发环境、版本匹配、编译套件、依赖库、插件路径、发布部署每一步都有坑。我这些年帮人看过太多这种包也和这种“示例”的坑打过好几年交道。这篇文章不打算做成那种“复制粘贴就能跑”的速食教程而是想站在我自己的实操角度把“拿到一个 Qt 窗口程序示例包之后从解压到运行再改造成自己的程序最后打包发给别人”的完整链路捋一遍。包括版本怎么选、组件怎么勾、Kit 怎么匹配、满屏红色报错到底在说什么、怎么用 windeployqt 做发布以及几个每次都会有人踩的雷。适合手里刚好有一个别人分享的 Qt 示例却不知道从哪下手的人也适合已经跑过几个 Demo、但一换机器部署就崩的人。1. 示例包里挖出的第一个问题环境不匹配1.1 一个 .rar 里通常会有什么典型的 Qt 窗口程序示例包里面往往同时出现这几类东西源码工程.pro文件或CMakeLists.txt外加一堆.cpp、.h、.ui编译好的可执行文件Windows 下就是.exe但大概率没带动态库资源文件图片、qss 样式、字体、翻译文件某些包还会混进一个build目录全是作者机器上编译出来的中间产物拿到这种压缩包我建议先干一件事判断它是谁编译的、用什么 Qt 版本、用什么编译器编译的。判断依据很容易找看 exe 的生成路径。比如窗口标题栏或 Creator 的构建目录写着build-xxx-Desktop_Qt_5_15_2_MSVC2019_64bit-Release说明对方用的是 Qt 5.15.2 加 MSVC2019 64 位套件。看.pro里QT 写了什么。如果只有core gui那大概率不是 Qt5 的 widgets 窗口程序Qt5 窗口程序基本都会写QT widgets。看有没有.pro.user文件。Qt Creator 会用这个文件记录上一次使用的 Kit虽然路径在别人机器上可能失效但 Kit 名称可以作为很好的参考。如果包里既有源码又有 exe我一般会直接跳过 exe先看.pro和.user。因为 exe 大概率跑不起来就算跑起来了你也看不到代码运行逻辑对学习帮助不大。真正有价值的是源码和工程配置。1.2 为什么双击 exe 会失败Qt 不是一个把静态库直接编进 exe 的框架虽然理论上可以静态编译但实践中绝大多数示例都是动态链接。程序启动时Windows 加载器会去寻找Qt5Core.dll、Qt5Widgets.dll、Qt5Gui.dll这类动态库以及 QPA 平台插件qwindows.dll。一旦找不到或者版本不匹配就会出现两种典型弹窗缺少某个 Qt dll 的黄色弹窗提示你程序无法启动或者no Qt platform plugin could be initialized这条更迷惑人因为它说明 dll 可能找到了但平台插件加载失败既然 exe 这么容易出问题那拿到示例包的正确思路就应该是先找源码再看 .pro最后再谈运行。这个判断原则能帮你少走很多弯路也正好呼应了这个压缩包最常见的“环境不匹配”问题。2. 装对 Qt 版本之前先想清楚三件事2.1 版本选择5.15.2 仍然是稳妥的保守派现在 Qt 官方已经把重心放到 6.x 了6.5、6.6、6.7 都陆续发布网上新教程也开始往 Qt6 靠。但我实际带项目、帮人看示例代码时发现80% 以上的存量示例还是 Qt5 系尤其 5.15.2 和 5.12.12 这两个版本出镜率最高。为什么5.15.2 是 Qt 5 系列里最容易获取的 LTS 版本之一大量教程、示例、开源项目都是按它写的。5.12.12 也是 LTS但年代偏老有些新特性对应的接口在它身上并不存在。Qt 6 的改动非常大模块合并、QRegExp被移除、高 DPI 策略变化、某些类头文件路径也变了。很多老示例包在 Qt6 下根本编译不过。所以我的建议很直接手里的示例如果没有特别说明基于 Qt6优先装 Qt 5.15.2。先在 5 系跑通后面再考虑往 Qt6 迁移。否则你会浪费大量时间在“这段代码为什么编译不过”上而问题的本质其实是版本迁移问题不是你的代码问题。这个观念一定要先立住。2.2 下载慢和离线安装包的处理Qt 官方在线安装器需要登录账号下载速度在国内网络环境下经常让人没脾气。常见的解决方案有两类使用国内镜像源。中科大、清华、阿里都有 Qt 镜像安装时可以手动把下载地址替换成镜像地址也可以直接下载镜像站打包好的离线安装包。寻找 5.15.2 对应的离线安装包。一次下载完安装时勾选组件即可省去在线安装器反复下载的痛苦。这里有一个背景很多人不知道Qt 5.15 之后的版本开源版不再提供传统离线安装包或者仅面向商业用户开放。5.15.2 是很多开发者刻意封存在手中的“最后一代完整离线体验”版本这也是为什么网上流传的示例包大多写着需要 5.15.2。2.3 组件与 Kit 匹配MSVC 不等于 MinGW安装 Qt 时有一个非常关键的坑编译器套件必须与你要编译的代码来源匹配。如果你手里的示例是用 MSVC2019 64bit 编译的你本地最好也装 MSVC 套件如果只有 MinGW打开一个 MSVC 的工程有时能编但遇到.pro里的msvc{}条件块或者代码用了 MSVC 特有头文件就会直接失败。判断示例原来用哪个 Kit方法很简单在 Qt Creator 打开项目后左侧选择“项目”看当前构建套件Kits是哪一个。如果是Desktop Qt 5.15.2 MSVC2019 64bit但你电脑上根本没装 Visual Studio 的 C 桌面开发组件那要么去装要么把工程配置切换成 MinGW。这里顺便解决一个热搜里出现频率很高的报错:-1: error: dependent ..\..\..\..\allinstall\qt\5.15.2\msvc2019\include\qtw...这个报错的核心原因通常在.pro或.pri文件里出现了硬编码绝对路径比如作者机器上的allinstall\qt\5.15.2\msvc2019\include换了一台机器自然不存在。解决办法分三步打开.pro和.pri搜索allinstall或INCLUDEPATH把绝对路径改成相对路径或环境变量。检查 Kit 的 mkspec 是否选错。你明明用 MinGW结果 mkspecs 指向了 msvc2019就会自动去读 MSVC 的头文件路径。如果上面两步解决不了直接把相关INCLUDEPATH ...行手动指到你本地 Qt 安装目录下的 include 路径。这个错误信息极其具有迷惑性很多人以为 Qt 装坏了其实用文本搜索.pro、.pri、CMakeLists.txt三步走五分钟内就能定位。3. 跑通示例窗口的完整链路与两个高频报错3.1 Qt Creator 的打开方式拿到源码之后正确的打开姿势是打开 Qt Creator菜单 File → Open File or Project选中.pro文件或CMakeLists.txt。如果弹出 Configure Project 对话框左侧会列出你已安装的 Kit选择一个和示例匹配的 Kit然后点 Configure Project。等待 qmake 或 CMake 解析完成右下角进度条走完后点左下角的绿色运行按钮快捷键是 CtrlR。这里有个很多人不知道的小技巧如果.pro文件和源码不在同一层目录或者工程里有相对路径引用资源最好从资源管理器里复制完整路径再粘贴进去不要在最近打开列表里乱选。因为 Qt Creator 会缓存工程路径路径里出现中文或空格时某些老版本会出莫名其妙的解析问题。3.2 编译通过但运行崩溃或黑屏怎么办编译通过只能说明语法没问题运行时的崩溃往往更让新手绝望。最常见的问题有这么几类高 DPI 缩放导致界面错乱。解决方案是在main.cpp里创建QApplication之前设置高 DPI 缩放策略#include QApplication int main(int argc, char *argv[]) { QApplication::setHighDpiScaleFactorRoundingPolicy( Qt::HighDpiScaleFactorRoundingPolicy::PassThrough); QApplication app(argc, argv); // ... return app.exec(); }找不到 QPA plugin。在 Qt Creator 里按 CtrlR 运行一般不出现因为 Creator 会自动设置QT_QPA_PLATFORM_PLUGIN_PATH环境变量。但你把 exe 拿出来单独运行就会触发这个报错。记住一个结论在 Creator 里能跑不代表 exe 能跑。程序秒退但没有任何提示。先检查是不是编码问题导致的中文乱码崩溃再查构造函数里有没有空指针解引用最后看是否缺少运行时依赖。处理这类崩溃的通用思路是先看 Qt Creator 的“应用程序输出”面板再开一个命令行窗口直接运行 exe把 stdout 和 stderr 全部打出来。我是强烈建议初学者从一开始就养成看输出的习惯而不是一看到崩溃就重装 Qt。3.3 两个高频报错的人工定位链路第一个是编译报错Cannot find file: xxx.pro大概率是因为你用记事本改了.pro文件的编码改成 GBK 或者无 BOM 的 UTF-8 后qmake 解析失败。处理方式是用 Qt Creator 打开该文件另存为 UTF-8 with BOM 格式。这听起来很玄学但确实能解决一批工程文件打不开的问题。第二个是No such file or directory指向某个.h但你明明看到头文件就躺在源码目录里。原因通常是头文件没被声明到.pro的HEADERS 或INCLUDEPATH 里。qmake 体系下头文件路径必须显式声明不像 CMake 那样会自动扫描一部分目录。我看到过不少人把整个文件夹拖进工程但忘了补路径结果编译器就是找不到头文件。只要把这两个问题的根因讲清楚初学者再遇到时就不会慌张了它们本质上都是工程配置问题不是 Qt 本身的问题。4. 把示例改造成能用的工具四个高频扩展点很多人的真实需求不是“跑通一个空窗口”而是要把示例改造成能完成实际任务的工具。从大家常搜的关键词能看到最常往窗口程序里塞的就是绘图、串口、网络请求、鼠标事件模拟这四件事。我挨个说下值得注意的点。4.1 QCustomPlot kissfft时域波形到频域频谱信号处理类的小工具许多人的选择是 Qt 窗口加 QCustomPlot 绘图。QCustomPlot 是纯源码组件只有一个qcustomplot.h和qcustomplot.cpp加进工程非常方便// MainWindow 构造里初始化绘图区域 ui-plotWidget-addGraph(); ui-plotWidget-xAxis-setLabel(频率 / Hz); ui-plotWidget-yAxis-setLabel(幅值);至于时域到频域的转换有人用 QCustomPlot 自带的 FFT也有人集成 kissfft。kissfft 的好处是体积小、纯 C 实现、不引入庞大的 FFTW 依赖库。一个非常常见的坑FFT 计算完成后很多人直接把频谱幅值对应的下标当作 X 轴坐标结果画出来一堆横轴没意义的柱状图。正确的做法是换算成真实频率double freqResolution sampleRate / fftSize; // 频率分辨率 double maxFreq sampleRate / 2.0; // 奈奎斯特频率 ui-plotWidget-xAxis-setRange(0, maxFreq);如果你还想把 X 轴画成从负频率到正频率那就是另一个话题了。但核心观点是FFT 的下标必须乘以频率分辨率才能对应到 Hz。4.2 串口编程的基本套路Qt 的串口模块用起来不算复杂核心类就是QSerialPortm_serial new QSerialPort(this); m_serial-setPortName(COM3); m_serial-setBaudRate(9600); m_serial-open(QIODevice::ReadWrite); connect(m_serial, QSerialPort::readyRead, this, MainWindow::onReadyRead);这里我要单独说一个非常隐蔽的坑在 Windows 上USB 转串口设备每次插拔后串口号都可能改变。如果代码里写死COM3下次可能就不存在了。所以界面里最好留一个串口选择下拉框程序启动时枚举所有可用串口再把 open 操作放到用户点击连接之后而不是一启动就 open。配合QSerialPortInfo::availablePorts()可以很轻松实现串口枚举。4.3 GET/POST 请求的两个经典报错网友们问得最多的两个报错是“qt post请求 无法获取”和“request method post not supported”这两个放在一起讲因为根因几乎都是同一个服务端实际收到的请求不是 POST。最常见的罪魁祸首是QNetworkAccessManager的用法QNetworkRequest request; request.setUrl(QUrl(http://example.com/api)); request.setHeader(QNetworkRequest::ContentTypeHeader, application/x-www-form-urlencoded); QNetworkReply *reply manager-post(request, body.toUtf8());看着没问题对吧问题往往出在你没有意识到前面某处又调用了一次setUrl或者你习惯把参数拼接在 URL 上此时再用post()服务端看到请求行里写着 GET自然返回 POST not supported。另一个高频坑是 HTTPS 证书。开发环境用自签证书时QNetworkAccessManager默认会拒绝连接。你必须在代码里对 SSL 错误做处理仅限调试生产环境不建议忽略。很多人配了一堆证书还是不行就开始怀疑 Qt 网络模块坏了其实只是签名信任问题。4.4 模拟鼠标点击事件常有人问“qt模拟鼠标点击事件”这多半要做自动化测试或远程控制类工具。在 Qt 里可以用QTest::mouseClick也可以用 Windows 的SendInput。如果希望鼠标点击在不真正移动物理鼠标的情况下生效用SendInput更合适。但在自己的 Qt 窗口内部模拟点击时要注意把全局坐标转换成 widget 坐标再构造QMouseEvent投递才能命中正确的控件。实际经验是先用widget-mapFromGlobal(QCursor::pos())拿到相对坐标再决定发 mouse press 和 mouse release这样消息队列不会出现点击被吞掉的现象。4.5 顺带补一个翻译和三维曲线的坑有人还会搜“qt 翻译”和“qt绘制三维曲线”。翻译这块记得tr()包住用户可见字符串然后通过lupdate生成.ts文件再用lrelease生成.qm最后在main.cpp里加载 QTranslator。三维曲线用Qt Data Visualization模块的Q3DSurface或Q3DScatter注意安装 Qt 时要勾选 Data Visualization 组件否则编译会提示找不到模块头文件。5. windeployqt 打包从本机能跑到别人电脑上黑屏的排查5.1 标准打包流程Qt 的发布不像 Go、Rust 那样拷一个 exe 就完事。Windows 下最省事的官方工具是windeployqt# 把编译好的 exe 单独放到一个目录例如 D:\release cd /d D:\release D:\Qt\5.15.2\msvc2019_64\bin\windeployqt.exe myapp.exe这个命令会把依赖的Qt5Core.dll、Qt5Widgets.dll、platforms/qwindows.dll等文件自动复制到 exe 旁边。跑完之后请一定再用Dependencies或Process Explorer这类工具整体检查一遍 exe 的依赖不要只看 Qt 目录就认为收工了。比如你用了QSerialPort某些版本的 windeployqt 不会自动带上Qt5SerialPort.dll需要手动从 Qt 安装目录的 bin 下复制过去。5.2 “no Qt platform plugin” 的完整排查这个报错被完整搜出来的上下文是“windows no qt platform plugin could be initialized reinstalling the applicat...”。很多人已经到了“重装应用”这一步但问题根本不在应用本身。我把它拆成四步排查exe 旁边有没有platforms/qwindows.dll没有就从 Qt 安装目录的plugins/platforms复制或者重跑 windeployqt。有qwindows.dll但仍然报错检查它和 exe 的 Qt 版本、编译器是否一致。MinGW 编译的 exe 配上 MSVC 的qwindows.dll大概率起不来。版本一致还是报错检查环境变量QT_QPA_PLATFORM_PLUGIN_PATH。如果它指向一个错误目录程序会优先读取它而忽略 exe 旁边的 platforms。以上都没问题时看看是不是缺了 VC 运行库比如msvcp140.dll和vcruntime140.dll尤其是用 MSVC 编译出来的程序。很多人一看到这句英文就在搜索引擎里搜 reinstalling the application然后重装 Qt、重装系统其实它只是 Qt 启动时找不到 QPA 插件后的标准兜底提示和程序业务逻辑完全无关。5.3 压缩成 .rar 交付的清单回到“Qt窗口程序示例.rar”这个标题本身。我平时如果要把示例交付给别人会压这几样东西完整源码但绝对不带 build 目录一个 README写明 Qt 版本、Kit、第三方库版本、Qt Creator 打开步骤一个 release 目录包含 exe、依赖 dll 和 platforms 目录如果涉及串口或网络再写一份运行环境说明很多 .rar 下载下来打不开、跑不了就是因为作者把 build 目录塞了进去但没放依赖库也没写 README。你要自己做示例包请一定把依赖说清楚这能减少至少 60% 的“售后”咨询。6. 个人工具箱我调试 Qt 程序的一些土办法6.1 IDE 之争Qt Creator 还是 VS Code热搜里有“qt creator vs vs code:2024年qt开发ide终极选择指南”。我的个人结论很简单纯 Qt 工程尤其是带.ui文件的工程直接用 Qt Creator。VS Code 要配置 CMake、Ninja、Qt Designer 插件、环境变量依赖链很长出问题的排查成本很高。VS Code 的优势在于代码提示和编辑体验但调试 Qt 窗口程序时Qt Creator 自带的 Designer、信号槽可视化、Qt 调试助手都省心得多。如果你确实想在 VS Code 里用 Qt至少要装 Qt 官方扩展和 Qt Designer 插件并且在 CMake 里指定 Qt 的路径cmake.configureSettings: { CMAKE_PREFIX_PATH: D:/Qt/5.15.2/msvc2019_64 }我自己用了一圈之后的体验是VS Code 适合写纯 C 逻辑一碰到界面、对象树、信号槽还是回 Qt Creator 更顺手。6.2 崩溃调试的土办法程序崩溃的瞬间往往来不及开调试器所以我的做法是用日志来缩小范围在main.cpp里安装qInstallMessageHandler把qDebug、qWarning、qCritical全部写到日志文件。在关键函数入口写一行日志比如enter MainWindow::onClicked崩溃后看日志最后一条出现在哪就能快速二分定位。如果崩溃点在 Qt 内部而不是自己的代码里大部分是内存破坏或野指针用 AddressSanitizer 重新编译一遍往往能直接抓到越界写的位置。这套土办法帮我在没有图形调试环境的情况下排过不少问题。这里多提一句Linux 下跑 Qt 跟 Windows 完全不一样。Windows 是 exe 旁边放 dllLinux 则依赖ldconfig和LD_LIBRARY_PATH。如果你把 Windows 的发布思维直接搬到 Linux就会遇到error while loading shared libraries。6.3 踩坑后的反思我最早接触 Qt 时也拿到过一个类似的“Qt窗口程序示例.rar”解压、双击、报错、重装、再报错折腾了一周都没跑起来。后来才发现问题不过是我装了 Qt6却拿着 Qt5 的示例代码硬编。那段经历给我的教训就是先认版本再认 Kit然后才是编译和调试。如果你现在手里正卡在某个示例包上我建议先打开.pro文件第一行注释看一眼把编译报错的前 50 行完整读一遍而不是只看最下面那一行然后再决定要不要重装环境。多数时候问题不在环境而在路径和版本。最后分享一个小技巧把下载回来的示例包复制到纯英文路径下再解压比如D:\work\qt_demo。很多 Qt 版本的编译器和 qmake 对中文路径、空格目录支持不好这一步能帮你避免大量半夜崩溃。本文还有配套的精品资源点击获取 Qt窗口程序示例包：从解压到部署的完整避坑指南
简介这是一份Qt窗口程序入门示例面向刚接触Qt Widgets的开发者用于演示从零搭建多窗口GUI应用。压缩包共9个文件大小仅5KB包含3个cpp源文件、2个h头文件、2个ui界面定义文件以及pro工程文件和user配置涵盖源码、界面和工程配置可直接用Qt Creator打开编译。示例以“2Wdiget”双窗口为主展示登录对话框与主窗口的跳转逻辑覆盖QWidget/QMainWindow派生、界面布局、信号槽触发登录验证以及事件循环启动时机同时演示了如何管理两个独立窗口的显示与关闭并让读者直观理解ui文件与cpp头文件的分工方式。已有776人学习适合课程设计、毕业设计和自学练手也可作为后续加入数据库、网络通信等复杂功能的启动模板。 拿到一个叫Qt窗口程序示例.rar的文件大多数人第一反应是解压、双击 exe然后面对两种结果要么窗口压根没弹出来要么弹一个no Qt platform plugin could be initialized的亮黄色窗口顺带还提示你 reinstalling the application。这个压缩包看似只是一个小示例背后涉及的环节却足够劝退一批刚入门的 Qt 学习者开发环境、版本匹配、编译套件、依赖库、插件路径、发布部署每一步都有坑。我这些年帮人看过太多这种包也和这种“示例”的坑打过好几年交道。这篇文章不打算做成那种“复制粘贴就能跑”的速食教程而是想站在我自己的实操角度把“拿到一个 Qt 窗口程序示例包之后从解压到运行再改造成自己的程序最后打包发给别人”的完整链路捋一遍。包括版本怎么选、组件怎么勾、Kit 怎么匹配、满屏红色报错到底在说什么、怎么用 windeployqt 做发布以及几个每次都会有人踩的雷。适合手里刚好有一个别人分享的 Qt 示例却不知道从哪下手的人也适合已经跑过几个 Demo、但一换机器部署就崩的人。1. 示例包里挖出的第一个问题环境不匹配1.1 一个 .rar 里通常会有什么典型的 Qt 窗口程序示例包里面往往同时出现这几类东西源码工程.pro文件或CMakeLists.txt外加一堆.cpp、.h、.ui编译好的可执行文件Windows 下就是.exe但大概率没带动态库资源文件图片、qss 样式、字体、翻译文件某些包还会混进一个build目录全是作者机器上编译出来的中间产物拿到这种压缩包我建议先干一件事判断它是谁编译的、用什么 Qt 版本、用什么编译器编译的。判断依据很容易找看 exe 的生成路径。比如窗口标题栏或 Creator 的构建目录写着build-xxx-Desktop_Qt_5_15_2_MSVC2019_64bit-Release说明对方用的是 Qt 5.15.2 加 MSVC2019 64 位套件。看.pro里QT 写了什么。如果只有core gui那大概率不是 Qt5 的 widgets 窗口程序Qt5 窗口程序基本都会写QT widgets。看有没有.pro.user文件。Qt Creator 会用这个文件记录上一次使用的 Kit虽然路径在别人机器上可能失效但 Kit 名称可以作为很好的参考。如果包里既有源码又有 exe我一般会直接跳过 exe先看.pro和.user。因为 exe 大概率跑不起来就算跑起来了你也看不到代码运行逻辑对学习帮助不大。真正有价值的是源码和工程配置。1.2 为什么双击 exe 会失败Qt 不是一个把静态库直接编进 exe 的框架虽然理论上可以静态编译但实践中绝大多数示例都是动态链接。程序启动时Windows 加载器会去寻找Qt5Core.dll、Qt5Widgets.dll、Qt5Gui.dll这类动态库以及 QPA 平台插件qwindows.dll。一旦找不到或者版本不匹配就会出现两种典型弹窗缺少某个 Qt dll 的黄色弹窗提示你程序无法启动或者no Qt platform plugin could be initialized这条更迷惑人因为它说明 dll 可能找到了但平台插件加载失败既然 exe 这么容易出问题那拿到示例包的正确思路就应该是先找源码再看 .pro最后再谈运行。这个判断原则能帮你少走很多弯路也正好呼应了这个压缩包最常见的“环境不匹配”问题。2. 装对 Qt 版本之前先想清楚三件事2.1 版本选择5.15.2 仍然是稳妥的保守派现在 Qt 官方已经把重心放到 6.x 了6.5、6.6、6.7 都陆续发布网上新教程也开始往 Qt6 靠。但我实际带项目、帮人看示例代码时发现80% 以上的存量示例还是 Qt5 系尤其 5.15.2 和 5.12.12 这两个版本出镜率最高。为什么5.15.2 是 Qt 5 系列里最容易获取的 LTS 版本之一大量教程、示例、开源项目都是按它写的。5.12.12 也是 LTS但年代偏老有些新特性对应的接口在它身上并不存在。Qt 6 的改动非常大模块合并、QRegExp被移除、高 DPI 策略变化、某些类头文件路径也变了。很多老示例包在 Qt6 下根本编译不过。所以我的建议很直接手里的示例如果没有特别说明基于 Qt6优先装 Qt 5.15.2。先在 5 系跑通后面再考虑往 Qt6 迁移。否则你会浪费大量时间在“这段代码为什么编译不过”上而问题的本质其实是版本迁移问题不是你的代码问题。这个观念一定要先立住。2.2 下载慢和离线安装包的处理Qt 官方在线安装器需要登录账号下载速度在国内网络环境下经常让人没脾气。常见的解决方案有两类使用国内镜像源。中科大、清华、阿里都有 Qt 镜像安装时可以手动把下载地址替换成镜像地址也可以直接下载镜像站打包好的离线安装包。寻找 5.15.2 对应的离线安装包。一次下载完安装时勾选组件即可省去在线安装器反复下载的痛苦。这里有一个背景很多人不知道Qt 5.15 之后的版本开源版不再提供传统离线安装包或者仅面向商业用户开放。5.15.2 是很多开发者刻意封存在手中的“最后一代完整离线体验”版本这也是为什么网上流传的示例包大多写着需要 5.15.2。2.3 组件与 Kit 匹配MSVC 不等于 MinGW安装 Qt 时有一个非常关键的坑编译器套件必须与你要编译的代码来源匹配。如果你手里的示例是用 MSVC2019 64bit 编译的你本地最好也装 MSVC 套件如果只有 MinGW打开一个 MSVC 的工程有时能编但遇到.pro里的msvc{}条件块或者代码用了 MSVC 特有头文件就会直接失败。判断示例原来用哪个 Kit方法很简单在 Qt Creator 打开项目后左侧选择“项目”看当前构建套件Kits是哪一个。如果是Desktop Qt 5.15.2 MSVC2019 64bit但你电脑上根本没装 Visual Studio 的 C 桌面开发组件那要么去装要么把工程配置切换成 MinGW。这里顺便解决一个热搜里出现频率很高的报错:-1: error: dependent ..\..\..\..\allinstall\qt\5.15.2\msvc2019\include\qtw...这个报错的核心原因通常在.pro或.pri文件里出现了硬编码绝对路径比如作者机器上的allinstall\qt\5.15.2\msvc2019\include换了一台机器自然不存在。解决办法分三步打开.pro和.pri搜索allinstall或INCLUDEPATH把绝对路径改成相对路径或环境变量。检查 Kit 的 mkspec 是否选错。你明明用 MinGW结果 mkspecs 指向了 msvc2019就会自动去读 MSVC 的头文件路径。如果上面两步解决不了直接把相关INCLUDEPATH ...行手动指到你本地 Qt 安装目录下的 include 路径。这个错误信息极其具有迷惑性很多人以为 Qt 装坏了其实用文本搜索.pro、.pri、CMakeLists.txt三步走五分钟内就能定位。3. 跑通示例窗口的完整链路与两个高频报错3.1 Qt Creator 的打开方式拿到源码之后正确的打开姿势是打开 Qt Creator菜单 File → Open File or Project选中.pro文件或CMakeLists.txt。如果弹出 Configure Project 对话框左侧会列出你已安装的 Kit选择一个和示例匹配的 Kit然后点 Configure Project。等待 qmake 或 CMake 解析完成右下角进度条走完后点左下角的绿色运行按钮快捷键是 CtrlR。这里有个很多人不知道的小技巧如果.pro文件和源码不在同一层目录或者工程里有相对路径引用资源最好从资源管理器里复制完整路径再粘贴进去不要在最近打开列表里乱选。因为 Qt Creator 会缓存工程路径路径里出现中文或空格时某些老版本会出莫名其妙的解析问题。3.2 编译通过但运行崩溃或黑屏怎么办编译通过只能说明语法没问题运行时的崩溃往往更让新手绝望。最常见的问题有这么几类高 DPI 缩放导致界面错乱。解决方案是在main.cpp里创建QApplication之前设置高 DPI 缩放策略#include QApplication int main(int argc, char *argv[]) { QApplication::setHighDpiScaleFactorRoundingPolicy( Qt::HighDpiScaleFactorRoundingPolicy::PassThrough); QApplication app(argc, argv); // ... return app.exec(); }找不到 QPA plugin。在 Qt Creator 里按 CtrlR 运行一般不出现因为 Creator 会自动设置QT_QPA_PLATFORM_PLUGIN_PATH环境变量。但你把 exe 拿出来单独运行就会触发这个报错。记住一个结论在 Creator 里能跑不代表 exe 能跑。程序秒退但没有任何提示。先检查是不是编码问题导致的中文乱码崩溃再查构造函数里有没有空指针解引用最后看是否缺少运行时依赖。处理这类崩溃的通用思路是先看 Qt Creator 的“应用程序输出”面板再开一个命令行窗口直接运行 exe把 stdout 和 stderr 全部打出来。我是强烈建议初学者从一开始就养成看输出的习惯而不是一看到崩溃就重装 Qt。3.3 两个高频报错的人工定位链路第一个是编译报错Cannot find file: xxx.pro大概率是因为你用记事本改了.pro文件的编码改成 GBK 或者无 BOM 的 UTF-8 后qmake 解析失败。处理方式是用 Qt Creator 打开该文件另存为 UTF-8 with BOM 格式。这听起来很玄学但确实能解决一批工程文件打不开的问题。第二个是No such file or directory指向某个.h但你明明看到头文件就躺在源码目录里。原因通常是头文件没被声明到.pro的HEADERS 或INCLUDEPATH 里。qmake 体系下头文件路径必须显式声明不像 CMake 那样会自动扫描一部分目录。我看到过不少人把整个文件夹拖进工程但忘了补路径结果编译器就是找不到头文件。只要把这两个问题的根因讲清楚初学者再遇到时就不会慌张了它们本质上都是工程配置问题不是 Qt 本身的问题。4. 把示例改造成能用的工具四个高频扩展点很多人的真实需求不是“跑通一个空窗口”而是要把示例改造成能完成实际任务的工具。从大家常搜的关键词能看到最常往窗口程序里塞的就是绘图、串口、网络请求、鼠标事件模拟这四件事。我挨个说下值得注意的点。4.1 QCustomPlot kissfft时域波形到频域频谱信号处理类的小工具许多人的选择是 Qt 窗口加 QCustomPlot 绘图。QCustomPlot 是纯源码组件只有一个qcustomplot.h和qcustomplot.cpp加进工程非常方便// MainWindow 构造里初始化绘图区域 ui-plotWidget-addGraph(); ui-plotWidget-xAxis-setLabel(频率 / Hz); ui-plotWidget-yAxis-setLabel(幅值);至于时域到频域的转换有人用 QCustomPlot 自带的 FFT也有人集成 kissfft。kissfft 的好处是体积小、纯 C 实现、不引入庞大的 FFTW 依赖库。一个非常常见的坑FFT 计算完成后很多人直接把频谱幅值对应的下标当作 X 轴坐标结果画出来一堆横轴没意义的柱状图。正确的做法是换算成真实频率double freqResolution sampleRate / fftSize; // 频率分辨率 double maxFreq sampleRate / 2.0; // 奈奎斯特频率 ui-plotWidget-xAxis-setRange(0, maxFreq);如果你还想把 X 轴画成从负频率到正频率那就是另一个话题了。但核心观点是FFT 的下标必须乘以频率分辨率才能对应到 Hz。4.2 串口编程的基本套路Qt 的串口模块用起来不算复杂核心类就是QSerialPortm_serial new QSerialPort(this); m_serial-setPortName(COM3); m_serial-setBaudRate(9600); m_serial-open(QIODevice::ReadWrite); connect(m_serial, QSerialPort::readyRead, this, MainWindow::onReadyRead);这里我要单独说一个非常隐蔽的坑在 Windows 上USB 转串口设备每次插拔后串口号都可能改变。如果代码里写死COM3下次可能就不存在了。所以界面里最好留一个串口选择下拉框程序启动时枚举所有可用串口再把 open 操作放到用户点击连接之后而不是一启动就 open。配合QSerialPortInfo::availablePorts()可以很轻松实现串口枚举。4.3 GET/POST 请求的两个经典报错网友们问得最多的两个报错是“qt post请求 无法获取”和“request method post not supported”这两个放在一起讲因为根因几乎都是同一个服务端实际收到的请求不是 POST。最常见的罪魁祸首是QNetworkAccessManager的用法QNetworkRequest request; request.setUrl(QUrl(http://example.com/api)); request.setHeader(QNetworkRequest::ContentTypeHeader, application/x-www-form-urlencoded); QNetworkReply *reply manager-post(request, body.toUtf8());看着没问题对吧问题往往出在你没有意识到前面某处又调用了一次setUrl或者你习惯把参数拼接在 URL 上此时再用post()服务端看到请求行里写着 GET自然返回 POST not supported。另一个高频坑是 HTTPS 证书。开发环境用自签证书时QNetworkAccessManager默认会拒绝连接。你必须在代码里对 SSL 错误做处理仅限调试生产环境不建议忽略。很多人配了一堆证书还是不行就开始怀疑 Qt 网络模块坏了其实只是签名信任问题。4.4 模拟鼠标点击事件常有人问“qt模拟鼠标点击事件”这多半要做自动化测试或远程控制类工具。在 Qt 里可以用QTest::mouseClick也可以用 Windows 的SendInput。如果希望鼠标点击在不真正移动物理鼠标的情况下生效用SendInput更合适。但在自己的 Qt 窗口内部模拟点击时要注意把全局坐标转换成 widget 坐标再构造QMouseEvent投递才能命中正确的控件。实际经验是先用widget-mapFromGlobal(QCursor::pos())拿到相对坐标再决定发 mouse press 和 mouse release这样消息队列不会出现点击被吞掉的现象。4.5 顺带补一个翻译和三维曲线的坑有人还会搜“qt 翻译”和“qt绘制三维曲线”。翻译这块记得tr()包住用户可见字符串然后通过lupdate生成.ts文件再用lrelease生成.qm最后在main.cpp里加载 QTranslator。三维曲线用Qt Data Visualization模块的Q3DSurface或Q3DScatter注意安装 Qt 时要勾选 Data Visualization 组件否则编译会提示找不到模块头文件。5. windeployqt 打包从本机能跑到别人电脑上黑屏的排查5.1 标准打包流程Qt 的发布不像 Go、Rust 那样拷一个 exe 就完事。Windows 下最省事的官方工具是windeployqt# 把编译好的 exe 单独放到一个目录例如 D:\release cd /d D:\release D:\Qt\5.15.2\msvc2019_64\bin\windeployqt.exe myapp.exe这个命令会把依赖的Qt5Core.dll、Qt5Widgets.dll、platforms/qwindows.dll等文件自动复制到 exe 旁边。跑完之后请一定再用Dependencies或Process Explorer这类工具整体检查一遍 exe 的依赖不要只看 Qt 目录就认为收工了。比如你用了QSerialPort某些版本的 windeployqt 不会自动带上Qt5SerialPort.dll需要手动从 Qt 安装目录的 bin 下复制过去。5.2 “no Qt platform plugin” 的完整排查这个报错被完整搜出来的上下文是“windows no qt platform plugin could be initialized reinstalling the applicat...”。很多人已经到了“重装应用”这一步但问题根本不在应用本身。我把它拆成四步排查exe 旁边有没有platforms/qwindows.dll没有就从 Qt 安装目录的plugins/platforms复制或者重跑 windeployqt。有qwindows.dll但仍然报错检查它和 exe 的 Qt 版本、编译器是否一致。MinGW 编译的 exe 配上 MSVC 的qwindows.dll大概率起不来。版本一致还是报错检查环境变量QT_QPA_PLATFORM_PLUGIN_PATH。如果它指向一个错误目录程序会优先读取它而忽略 exe 旁边的 platforms。以上都没问题时看看是不是缺了 VC 运行库比如msvcp140.dll和vcruntime140.dll尤其是用 MSVC 编译出来的程序。很多人一看到这句英文就在搜索引擎里搜 reinstalling the application然后重装 Qt、重装系统其实它只是 Qt 启动时找不到 QPA 插件后的标准兜底提示和程序业务逻辑完全无关。5.3 压缩成 .rar 交付的清单回到“Qt窗口程序示例.rar”这个标题本身。我平时如果要把示例交付给别人会压这几样东西完整源码但绝对不带 build 目录一个 README写明 Qt 版本、Kit、第三方库版本、Qt Creator 打开步骤一个 release 目录包含 exe、依赖 dll 和 platforms 目录如果涉及串口或网络再写一份运行环境说明很多 .rar 下载下来打不开、跑不了就是因为作者把 build 目录塞了进去但没放依赖库也没写 README。你要自己做示例包请一定把依赖说清楚这能减少至少 60% 的“售后”咨询。6. 个人工具箱我调试 Qt 程序的一些土办法6.1 IDE 之争Qt Creator 还是 VS Code热搜里有“qt creator vs vs code:2024年qt开发ide终极选择指南”。我的个人结论很简单纯 Qt 工程尤其是带.ui文件的工程直接用 Qt Creator。VS Code 要配置 CMake、Ninja、Qt Designer 插件、环境变量依赖链很长出问题的排查成本很高。VS Code 的优势在于代码提示和编辑体验但调试 Qt 窗口程序时Qt Creator 自带的 Designer、信号槽可视化、Qt 调试助手都省心得多。如果你确实想在 VS Code 里用 Qt至少要装 Qt 官方扩展和 Qt Designer 插件并且在 CMake 里指定 Qt 的路径cmake.configureSettings: { CMAKE_PREFIX_PATH: D:/Qt/5.15.2/msvc2019_64 }我自己用了一圈之后的体验是VS Code 适合写纯 C 逻辑一碰到界面、对象树、信号槽还是回 Qt Creator 更顺手。6.2 崩溃调试的土办法程序崩溃的瞬间往往来不及开调试器所以我的做法是用日志来缩小范围在main.cpp里安装qInstallMessageHandler把qDebug、qWarning、qCritical全部写到日志文件。在关键函数入口写一行日志比如enter MainWindow::onClicked崩溃后看日志最后一条出现在哪就能快速二分定位。如果崩溃点在 Qt 内部而不是自己的代码里大部分是内存破坏或野指针用 AddressSanitizer 重新编译一遍往往能直接抓到越界写的位置。这套土办法帮我在没有图形调试环境的情况下排过不少问题。这里多提一句Linux 下跑 Qt 跟 Windows 完全不一样。Windows 是 exe 旁边放 dllLinux 则依赖ldconfig和LD_LIBRARY_PATH。如果你把 Windows 的发布思维直接搬到 Linux就会遇到error while loading shared libraries。6.3 踩坑后的反思我最早接触 Qt 时也拿到过一个类似的“Qt窗口程序示例.rar”解压、双击、报错、重装、再报错折腾了一周都没跑起来。后来才发现问题不过是我装了 Qt6却拿着 Qt5 的示例代码硬编。那段经历给我的教训就是先认版本再认 Kit然后才是编译和调试。如果你现在手里正卡在某个示例包上我建议先打开.pro文件第一行注释看一眼把编译报错的前 50 行完整读一遍而不是只看最下面那一行然后再决定要不要重装环境。多数时候问题不在环境而在路径和版本。最后分享一个小技巧把下载回来的示例包复制到纯英文路径下再解压比如D:\work\qt_demo。很多 Qt 版本的编译器和 qmake 对中文路径、空格目录支持不好这一步能帮你避免大量半夜崩溃。本文还有配套的精品资源点击获取