简介面向Qt初学者与需要快速搭建Qt开发环境的开发者这份演示示例通过一个完整小项目直观呈现了Qt软件安装后的基础工程配置与代码骨架。资源共包含六个文件其中两个cpp文件负责主程序与窗口逻辑一个h头文件完成类接口声明pro工程文件描述构建规则ui文件定义用户界面布局另有user文件保存项目级用户配置压缩包整体仅5KB结构精简、内容紧凑便于逐项对照。借助该示例读者可以理解Qt Creator创建项目时的默认目录结构将作者配套文章的安装步骤与demo配置逐一对应从而快速验证安装结果并掌握工程文件之间的协作关系。目前已有五百五十六人学习该示例适合希望高效入门Qt、快速验证环境配置并熟悉项目组织方式的开发者。 刚帮人看了一个Qt demo跑不起来的问题对方很完整地安装了Qt一运行就弹窗报 “no qt platform plugin could be initialized, reinstalling the application may fix this problem”。这大概是我遇到过的跟“Qt软件安装”相关最经典的报错没有之一。很多人以为把Qt装完、双击demo就能看到窗口但实际上从“装好Qt”到“真正把demo跑起来并分发给别人用”中间隔着一整套环境、插件、打包链路。这篇文章就围绕 Qt 软件安装 demo 示例 这条主线把从环境准备、demo编译运行、报错排查到最终打包分发的全流程写清楚希望能帮正在被Qt安装和demo折腾的朋友省下半天时间。我默认你至少已经决定要用Qt做点东西可能是一个串口调试工具、一个数据采集分析界面或者只是想跑通一个网上下载的demo。不管哪种情况下面讲的都是我在Windows和麒麟系统上实际踩过、验证过的路不是从文档里抄来的。1. 从“装了个Qt”到“跑通一个demo”中间到底差了哪几步1.1 为什么一个demo都能跑不起来很多刚接触Qt的人会有一种错觉Qt就是一个类似安装QQ的软件装好之后所有功能就都齐了。等他们从git上拉下来一个demo目录双击.pro或者用Qt Creator打开点击运行结果各种红色错误刷屏——找不到头文件、找不到Qt库、提示缺少平台插件。其实问题不在demo本身而是没有理解Qt作为一个C框架的组成方式。一个能正常运行的Qt程序至少需要三样东西Qt自身的库文件比如Qt5Widgets、Qt5Core、与当前编译器匹配的构建工具链qmake或cmake、MinGW/MSVC以及对应的平台插件。这三者只要有一个版本对不上或者路径不对程序就跑不起来。所以“安装Qt”不等于“配置好开发环境”更不等于“任何demo都能编译运行”。1.2 Qt环境的完整组成不止是SDK更是工具链以Qt 5.15为例从官方下载安装器时你会看到很多可勾选的组件它们分为几层Qt类库这是核心运行库按模块拆分QtWidgets、QtCharts、QCustomPlot是第三方库按编译套件区分MinGW 32/64位、MSVC 2017/2019等。你下载的demo如果是用MSVC编译的你只装了MinGW版本那大概率编译不过。开发工具Qt Creator是IDEqmake是构建工具还有cmake、ninja等。它们负责把源码编译成可执行文件。编译器Windows下常见的组合是MinGW自带gcc/g和MSVC需要单独安装Visual Studio Build Tools。麒麟系统下通常用的是系统自带的GCC配合Qt的gcc套件。平台插件这就是报错里提到的plugins/platforms目录。在Windows下是qwindows.dll在Linux/麒麟下是qxcb.so。程序启动时必须加载对应的平台插件否则就报no qt platform plugin。理解了这四层你就能明白安装Qt时如果组件选择不全或者编译器版本和Qt库不匹配demo是不可能顺利跑起来的。1.3 这篇文章要解决的具体场景本文围绕“Qt软件安装demo示例”这个主题会覆盖三个最常见的需求在Windows和麒麟系统上从零把Qt环境装好并跑通一个最小demo。安装或运行demo时遇到 no qt platform plugin、找不到库、编译失败等问题如何高效定位解决。把跑通的demo打包成可分发软件Windows exe、Linux可执行文件让没有安装Qt的机器也能运行。如果你是刚接触Qt的新手按照我下面的顺序一步步走基本能避免掉大多数坑。如果你已经遇到报错可以直接跳到第4章看排查链路。2. 把Qt环境装明白Windows和麒麟Linux两套实操流程2.1 从哪里下载、怎么选版本、用什么加速Qt的下载渠道主要有两个官方安装器和国内镜像。官方下载地址是download.qt.io但国内直连速度不稳定而且新版安装器强制要求注册账号。我个人的建议是直接使用国内镜像站下载离线安装包或者在线安装器。常用的国内镜像有清华、中科大、阿里云具体用法大同小异。以清华镜像为例进入https://mirrors.tuna.tsinghua.edu.cn/qt/里面有archive和online_installers等目录。如果只是日常开发推荐选择一个稳定版比如Qt 5.15.2它有独立的离线安装包一次下载完整安装过程不需要联网后续出问题也容易排查。版本选择上我推荐新手学习/个人工具选择qt-opensource-windows-x86-5.15.2.exeWindows或qt-opensource-linux-x64-5.15.2.runLinux。5.15.2是最后一个开源离线安装包版本稳定教程多坑基本都被踩平了。需要处理高分辨率或新硬件可以尝试Qt 6系列但注意QCustomPlot等第三方库在Qt6下需要重新编译部分旧demo不一定兼容。下载时注意平台和位数。Windows下64位系统优先选x86_64别选成arm或macOS包。2.2 Windows下安装Qt的完整步骤与组件勾选建议打开安装器选择安装目录时不要有中文和空格我习惯放在D:\Qt或C:\Qt。组件选择界面是最容易出错的地方这里给一份针对“跑demo开发小工具”的最低配置展开Qt 5.15.2MinGW 8.1.0 32-bit和64-bit二选一即可但建议64位。MinGW套件自带编译器省得单独装。MSVC 2019 64-bit如果你以后可能用Visual Studio开发选上否则可以不选因为MSVC套件还需要你装VS Build Tools体积很大。Qt WebEngine等大模块除非demo明确需要否则先不选。展开Developer and Designer ToolsQt Creator必选。MinGW 8.1.0这个选项本质是编译器工具链如果你上面选了MinGW套件这里会一起带上。CMake 或 Ninja看情况跑cmake类demo时会用到建议选上。安装完成后打开Qt Creator在“工具→选项→Kits”里能看到自动检测到的套件。一个正常的套件应该包含编译器、qmake、平台。如果这里显示红色感叹号说明某个组件缺失后面的编译大概率会失败。我个人的经验如果只是为了快速跑通一个demo宁可在组件勾选上保守一点也不要为了省硬盘空间把一个套件里核心的“Sources”也去掉。Qt Sources在后续用qcustomplot等第三方库时需要用到虽然多数情况用不到但遇到问题再补齐很费时间。2.3 麒麟系统下通过命令行安装Qt的实操热搜词里有很多人搜“麒麟系统怎么安装软件”“银河麒麟安装软件命令”“qt离线安装 麒麟x86”。这里说清楚一个关键点麒麟桌面系统通常基于Linux内核自带apt/dpkg包管理器但默认源里不一定有你想装的Qt版本。而且麒麟系统大多是X86架构少数是ARMWindows下那套安装流程不适用。最稳妥的方式是下载Qt官方的qt-opensource-linux-x64-5.15.2.run离线安装包或使用国内镜像。但在执行前先确认几件事# 查看系统架构 uname -m # 查看系统版本 cat /etc/os-release如果是X86_64架构直接给.run文件加执行权限并运行chmod x qt-opensource-linux-x64-5.15.2.run ./qt-opensource-linux-x64-5.15.2.run安装器会有图形界面组件选择逻辑和Windows一致记得勾选对应系统架构的Desktop gcc 64-bit套件。如果你是完全命令行环境也可以使用Qt安装器的--script方式但手动图形安装已经够用。安装到只剩依赖库问题时可能会遇到类似libxcb-xinerama0、libxkbcommon-x11-0等缺失导致Qt程序无法启动。这是因为Qt在Linux下依赖一批X11的库。用apt直接补齐sudo apt update sudo apt install libxcb-xinerama0 libxkbcommon-x11-0 libxcb-cursor0 libgl1-mesa-dev libglu1-mesa-dev麒麟系统基于Debian/Ubuntu系这些包名通用。装完依赖后再启动。不过第4章还会专门讲xcb相关报错这里先按下。2.4 安装后必须做的三件事装完Qt你一定不能直接去双击别人的demo先做三个最小验证否则后面出问题全是虚惊验证qmake版本打开命令行Windows是cmd或PowerShellLinux是终端运行qmake -v。如果提示找不到命令说明没有把Qt的bin目录加入环境变量PATH。Windows下可以手动加Linux下用export PATH/opt/Qt5.15.2/5.15.2/gcc_64/bin:$PATH临时加长期加就写进~/.bashrc。创建空窗口测试在Qt Creator里新建一个Qt Widgets Application默认就一个空窗口点击运行。如果这个能弹出来说明你的开发环境基本是通的。确认构建套件激活Qt Creator左下角会显示当前使用的套件比如Desktop Qt 5.15.2 MinGW 64-bit。如果显示“No kit”或者灰色直接换一个套件再试。这三件事做完问题在于环境本身还是在于demo基本能判断个八九不离十。3. 写一个能跑的最小demo编译、运行、验证一条龙3.1 创建或导入demo工程时的常见选择假设你已经有一个网上下载的demo目录里面可能有.pro文件qmake工程也可能有CMakeLists.txtcmake工程。在Qt Creator中导入方式都一样打开文件选择.pro或CMakeLists.txt然后选择一套Kit。需要注意一个高频问题如果你的demo用到了第三方模块比如qcustomplot、串口模块、QtCharts你的Qt安装时如果没勾选对应模块编译时会报“Qt module not found”。比如QT serialport但你的组件里没有安装Qt Serial Port模块编译直接失败。解决方法就是在安装时补勾选模块或者使用在线安装器维护添加组件。对于需要自己加入的第三方库如qcustomplot通常把它的qcustomplot.h和.cpp拷贝到你的demo源码目录然后在.pro里加入QT widgets printsupport SOURCES main.cpp qcustomplot.cpp HEADERS mainwindow.h qcustomplot.h3.2 一个最小demo的完整代码示例自己动手写一个最简单的demo既能验证环境也能为后续扩展做准备。我平时测试环境就写一个带按钮和简单绘图的窗口用来验证Qt Widgets和QCustomPlot是否正常。先创建一个空项目新建文件或项目→其他项目→空qmake项目.pro文件内容QT core gui widgets TARGET qt_demo_test TEMPLATE app SOURCES main.cpp HEADERS main.cpp内容#include QApplication #include QMainWindow #include QPushButton #include QVBoxLayout #include QWidget int main(int argc, char *argv[]) { QApplication a(argc, argv); QMainWindow win; QWidget *central new QWidget(win); QVBoxLayout *layout new QVBoxLayout(central); QPushButton *btn new QPushButton(Hello Qt Demo, central); layout-addWidget(btn); central-setLayout(layout); win.setCentralWidget(central); win.resize(400, 300); win.setWindowTitle(Qt Software Installation Demo); win.show(); return a.exec(); }编译运行如果弹出带按钮的窗口说明您的基础Qt环境已经完好。这个demo虽然简单但“安装→编译→运行”的链路已经打通之后替换成复杂的绘图demo、串口demo都是在这个基础上增加模块。如果想在demo里加入时域图转频域图的示例网上相关教程非常多核心步骤是用QCustomPlot的.graph(0)-setData(x,y)传入时域数据再通过FFTkissfft得到频域幅值并重新传入绘图曲线。不过fft相关的第三方库需要额外引入建议先把基础demo跑通再扩展。3.3 编译链接过程中的高频报错与含义我收集了几个在群聊里被反复问的编译报错对应原因其实很明确报错信息实际原因解决办法Qt5Core.dll not found程序运行时找不到Qt库把Qt bin目录加入PATH或用打包工具部署cannot find -lGLLinux下缺少OpenGL开发库sudo apt install libgl1-mesa-devmainwindow.h: No such file or directorydemo引用的头文件路径不对检查.pro文件是否包含对应文件路径Project ERROR: Unknown module(s) in QT: serialport未安装serialport模块安装时勾选Qt Serial Port或重新运行在线安装器安装C1083: Cannot open include file: qcustomplot.h缺少第三方库头文件将qcustomplot的源文件和头文件加入工程其中unknown module in QT是最多的几乎每次demo跑不起来都是因为原作者用了一个你没装的模块。所以在下载demo前最好先看一眼它的.pro文件里QT 后面写了什么再反查自己安装的Qt里有没有对应模块。安装器里每个模块名字对应关系不是100%直观比如“Qt Charts”对应QT charts“Qt Serial Port”对应QT serialport。3.4 运行demo时最常见的两类崩溃编译能过运行就崩比编译不过更让人头疼。最常见的两类第一类是我开头说的no qt platform plugin could be initialized。这个崩溃本质是找不到平台插件咱们在第4章详细讲。第二类是双击exe没反应或者报The application was unable to start correctly。这通常是因为Qt的DLL缺失。比如在Windows下程序运行时需要Qt5Widgets.dll、Qt5Core.dll等但这些DLL路径不在系统PATH里所以找不到。解决办法是把Qt的bin目录临时加入PATH再运行或者后面统一用windeployqt打包。在Linux/麒麟下是你加了PATH也还缺xcb但逻辑类似。这两种归类到“运行时依赖问题”而不是代码问题所以不要纠结代码逻辑对不对先检查环境。4. no qt platform plugin can be initialized一次典型的安装后运行失败排查4.1 这个报错的本质和触发场景很多人会问明明Qt安装成功了Qt Creator里运行demo也没问题但为什么直接去双击构建目录里的exe就报no qt platform plugin could be initialized首先要理解这个报错是程序运行时发生的不是编译时。Qt程序在启动时会到可执行文件相邻目录的platforms文件夹里找平台插件。步骤如下程序读取当前目录或硬编码路径。查找platforms/qwindows.dllWindows或platforms/libqxcb.soLinux。如果找不到或者加载失败比如依赖的库缺失就报告这个致命错误。在Qt Creator里运行没问题是因为Qt Creator会自动把%QTDIR%/plugins目录加入搜索路径所以一切正常。当你直接运行exe时没有这个天然的环境设置自然就报错了。4.2 从报错到解决的完整排查链路我给其他小伙伴排查时基本是按下面这个顺序推进的。你自己遇到同样问题时也可以依序检查第一步确认exe旁边有没有platforms目录。在Windows下你在demo构建目录里运行exe前需要在exe同级的platforms目录下放qwindows.dll。如果你是把exe拷到别处运行那基本必中这个错误。第二步确认qwindows.dll的配件是否齐全。很多情况下刚把platforms目录复制过来还是会报错那是因为qwindows.dll本身依赖Qt的很多共享库如Qt5Gui.dll、Qt5Core.dll。这些库要么在exe同目录要么在PATH里。用windeployqt可以一次性把所有库正确部署不要去手动复制很容易漏。第三步检查是不是编译器版本冲突。同一个platforms目录下有多个版本的qwindows不明显但如果你用的是MinGW编译的demo却把MSVC版本的qwindows.dll复制过去也会加载失败。最简单的办法是先用Qt Creator跑通再在“构建目录”看Qt Creator自动生成的部署文件是否正常。第四步在Windows下还可以用容错模式来验证cd /d your_exe_dir set PATHD:\Qt\5.15.2\mingw81_64\bin;D:\Qt\5.15.2\mingw81_64\plugins;%PATH% D:\Applications\你的程序.exe如果设置了以上路径后程序能跑起来就说明是插件和库路径缺失的问题不是程序本身的问题。如果是Linux/麒麟系统排查时切换成export QT_DEBUG_PLUGINS1 ./your_app设置这个环境变量后Qt会在终端打印插件加载的详细日志能准确看到是找不到库文件还是某个依赖动态库加载失败比如Cannot load library /opt/Qt/plugins/platforms/libqxcb.so再附加symbol lookup error。4.3 手动修复复制插件目录还是设置环境变量如果是临时调试直接在环境变量里加上插件路径是有效果的# Linux/麒麟 export QT_QPA_PLATFORM_PLUGIN_PATH/opt/Qt/5.15.2/gcc_64/plugins但是注意这个环境变量只是“临时让程序找到插件”不代表打包时能带对。真正发布给别人的程序必须把plugins和lib目录以正确结构放在exe旁边。通常的做法是app/ ├── your_app.exe ├── platforms/ │ └── qwindows.dll ├── styles/ ├── imageformats/ └── ... 各种Qt DLLWindows下windeployqt会自动生成这个结构Linux下用linuxdeployqt完成类似工作。4.4 麒麟系统下的xcb依赖问题热搜词里频繁出现“银河麒麟安装软件命令”“qt离线安装 麒麟x86”说明不少人是在麒麟环境里折腾Qt。麒麟系统下跑Qt demo最典型的报错就是libqxcb.so加载失败。即便QT_QPA_PLATFORM_PLUGIN_PATH指向正确还是可能提示依赖缺失Failed to load platform plugin xcb. Available platforms are: xcb Cannot load library /opt/Qt/5.15.2/gcc_64/plugins/platforms/libqxcb.so这种问题的根源通常是系统缺少Qt所需的X11相关库。上文提到的libxcb-xinerama0、libxkbcommon-x11-0等就是其中几个。最好直接安装一批常用依赖sudo apt update sudo apt install libxcb1 libx11-6 libx11-xcb1 libxkbcommon0 libxkbcommon-x11-0 libgl1-mesa-dev libegl1-mesa libxcb-xinerama0 libxcb-cursor0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-render-util0 libxcb-shape0 libxcb-xfixes0 libxcb-xkb1装完后重新运行Qt程序一般就能正常出现窗口。如果你是在麒麟系统上用命令行安装软件包记住apt是最常用的工具但不要随意更换系统源以免依赖版本错乱。5. 把demo变成可以发出去的软件打包发布的正确姿势5.1 为什么不能直接把exe拷给别人经常有人在群里发消息我编译好的exe大概10MB但是把整个目录拷给别人对方双击就报“缺少Qt5Core.dll”。原因是Qt程序是动态链接的10MB的exe只是你代码编译出来的体积它运行时要加载的Qt库动辄几十MB甚至上百MB。你需要把所有依赖的Qt模块DLL和插件一并带上。另外很多人只把bin目录里的DLL复制出来仍然会报platform plugin错误因为没有按插件目录结构摆放。这正是第4章问题的重演。5.2 Windows下用windeployqt打包的完整步骤用Qt自带的windeployqt工具可以自动扫描exe依赖的Qt模块并复制对应的DLL和插件到目标目录这是官方推荐的方式。在Qt命令行环境开始菜单里的“Qt 5.15.2 (MinGW 8.1.0 64-bit)”中执行cd /d D:\build\your_demo D:\Qt\5.15.2\mingw81_64\bin\windeployqt.exe your_app.exe执行完成后exe目录下会多出很多文件其中就包括platforms/qwindows.dll。还可以加参数指定额外模块比如你的demo用到了串口和Networkwindeployqt --network --serialport your_app.exe打包完成后把整个目录压缩发出去对方不需要安装Qt就能运行。不过我建议在本地测试时模拟一个干净环境先把当前环境变量中的Qt路径全部去掉再运行exe确认不依赖外部PATH。如果遇到工具提示Could not find qmake configuration多半是没有在Qt环境变量下运行。确保用的终端环境是从Qt Creator或Qt安装菜单启动的而不是普通cmd。5.3 Linux/麒麟系统下的打包思路Linux下没有官方一把梭的windeployqt社区常用的方案是使用linuxdeployqt工具但这个工具不是Qt官方出品针对不同发行版有时bug很多。我更推荐的稳妥做法是直接复制依赖库并写一个启动脚本。具体步骤假设你的demo二进制编译在/home/user/build/demo先把二进制复制到一个名为AppDir的目录。用ldd demo查看依赖的库路径把Qt相关的库比如libQt5Widgets.so.5复制到AppDir目录下。可以用脚本批量复制cp /opt/Qt/5.15.2/gcc_64/lib/libQt5Widgets.so.5 /home/user/AppDir/ cp /opt/Qt/5.15.2/gcc_64/lib/libQt5Gui.so.5 /home/user/AppDir/ cp /opt/Qt/5.15.2/gcc_64/lib/libQt5Core.so.5 /home/user/AppDir/ # 复制plugins/platforms mkdir -p /home/user/AppDir/platforms cp /opt/Qt/5.15.2/gcc_64/plugins/platforms/libqxcb.so /home/user/AppDir/platforms/编写一个启动脚本run.sh把LD_LIBRARY_PATH指向当前目录和Qt插件目录#!/bin/bash DIR$(dirname $(readlink -f $0)) export LD_LIBRARY_PATH$DIR:$DIR/platforms:$LD_LIBRARY_PATH export QT_QPA_PLATFORM_PLUGIN_PATH$DIR/platforms $DIR/demo授予执行权限后在目标机器上运行./run.sh即可。5.4 打完包还要做的验证清单我每次打包发给不同机器前都会走一遍这个验证清单少一项都可能被用户怼回来[ ] 在完全无Qt环境变量的终端或新用户下运行exe/可执行文件。[ ] 检查是否存在“no platform plugin”报错。[ ] 检查demo中用到的第三方库比如qcustomplot、fftw是否一并复制。[ ] 如果有中文路径确保程序安装路径不包含中文。[ ] 在麒麟系统或其他Linux发行版上测试一下缺少X11依赖时报错是否清晰必要时在启动脚本里自动检查并提示。这套流程做完你的demo才算真正从“自己电脑能跑”变成“别人也能跑”。6. 聊点还没提到但很实用的经验抛开具体命令Qt软件安装和demo跑通这件事说到底是一整套依赖管理的意识。很多人一味搜“qt demo 报错”却不去看.pro文件里的依赖、不去看plugins目录结构问题就总是复现。我自己踩过的最大的一个坑是为了省时间网上下载了一个所谓“绿色版Qt”结果编译器套件不完整导致后来所有demo都报Cannot find file: .pro白白折腾一整天。所以第一遍装Qt尽量用官方或清华镜像的完整离线安装包别用精简版。另一个我很少和别人提的细节安装Qt时MaintenanceTool其实是可以后期用来增删组件的。如果你最初少装了某个模块不需要重装整个Qt直接运行MaintenanceTool登录后选择“添加或移除组件”补勾选对应模块即可。很多人在群里问“qt的serialport模块怎么装”答案就是打开这个工具勾上再更新比重新下载安装包快得多。再有就是关于demo的本意。很多人拿到的“demo程序”往往是从网上拉下来的示例这类代码质量参差不齐用了老旧的Qt4语法或者依赖一个过时的第三方库。跑不通的时候先别怀疑是自己装错了先看版本兼容性。我最近遇到一个代码里写QString::toAscii在Qt5里根本没有这个函数所以编译就会报错。最好的处理方式是把这些代码改成Qt5/6的等价写法。最后说一个我自己的习惯我会在本地保留一个“最小demo模板”里面只有QMainWindow、一个按钮和一个QCustomPlot折线图。每次装完新的Qt环境或者帮别人检查环境问题我都先把这个模板跑一遍。如果模板能跑通就说明环境没问题问题出在对方的代码上如果模板都跑不通那就不用浪费时间看代码了。这个思路同样推荐给你能省下不少排查交互。本文还有配套的精品资源点击获取
Qt软件安装到Demo运行全流程：环境配置、报错排查与打包分发
简介面向Qt初学者与需要快速搭建Qt开发环境的开发者这份演示示例通过一个完整小项目直观呈现了Qt软件安装后的基础工程配置与代码骨架。资源共包含六个文件其中两个cpp文件负责主程序与窗口逻辑一个h头文件完成类接口声明pro工程文件描述构建规则ui文件定义用户界面布局另有user文件保存项目级用户配置压缩包整体仅5KB结构精简、内容紧凑便于逐项对照。借助该示例读者可以理解Qt Creator创建项目时的默认目录结构将作者配套文章的安装步骤与demo配置逐一对应从而快速验证安装结果并掌握工程文件之间的协作关系。目前已有五百五十六人学习该示例适合希望高效入门Qt、快速验证环境配置并熟悉项目组织方式的开发者。 刚帮人看了一个Qt demo跑不起来的问题对方很完整地安装了Qt一运行就弹窗报 “no qt platform plugin could be initialized, reinstalling the application may fix this problem”。这大概是我遇到过的跟“Qt软件安装”相关最经典的报错没有之一。很多人以为把Qt装完、双击demo就能看到窗口但实际上从“装好Qt”到“真正把demo跑起来并分发给别人用”中间隔着一整套环境、插件、打包链路。这篇文章就围绕 Qt 软件安装 demo 示例 这条主线把从环境准备、demo编译运行、报错排查到最终打包分发的全流程写清楚希望能帮正在被Qt安装和demo折腾的朋友省下半天时间。我默认你至少已经决定要用Qt做点东西可能是一个串口调试工具、一个数据采集分析界面或者只是想跑通一个网上下载的demo。不管哪种情况下面讲的都是我在Windows和麒麟系统上实际踩过、验证过的路不是从文档里抄来的。1. 从“装了个Qt”到“跑通一个demo”中间到底差了哪几步1.1 为什么一个demo都能跑不起来很多刚接触Qt的人会有一种错觉Qt就是一个类似安装QQ的软件装好之后所有功能就都齐了。等他们从git上拉下来一个demo目录双击.pro或者用Qt Creator打开点击运行结果各种红色错误刷屏——找不到头文件、找不到Qt库、提示缺少平台插件。其实问题不在demo本身而是没有理解Qt作为一个C框架的组成方式。一个能正常运行的Qt程序至少需要三样东西Qt自身的库文件比如Qt5Widgets、Qt5Core、与当前编译器匹配的构建工具链qmake或cmake、MinGW/MSVC以及对应的平台插件。这三者只要有一个版本对不上或者路径不对程序就跑不起来。所以“安装Qt”不等于“配置好开发环境”更不等于“任何demo都能编译运行”。1.2 Qt环境的完整组成不止是SDK更是工具链以Qt 5.15为例从官方下载安装器时你会看到很多可勾选的组件它们分为几层Qt类库这是核心运行库按模块拆分QtWidgets、QtCharts、QCustomPlot是第三方库按编译套件区分MinGW 32/64位、MSVC 2017/2019等。你下载的demo如果是用MSVC编译的你只装了MinGW版本那大概率编译不过。开发工具Qt Creator是IDEqmake是构建工具还有cmake、ninja等。它们负责把源码编译成可执行文件。编译器Windows下常见的组合是MinGW自带gcc/g和MSVC需要单独安装Visual Studio Build Tools。麒麟系统下通常用的是系统自带的GCC配合Qt的gcc套件。平台插件这就是报错里提到的plugins/platforms目录。在Windows下是qwindows.dll在Linux/麒麟下是qxcb.so。程序启动时必须加载对应的平台插件否则就报no qt platform plugin。理解了这四层你就能明白安装Qt时如果组件选择不全或者编译器版本和Qt库不匹配demo是不可能顺利跑起来的。1.3 这篇文章要解决的具体场景本文围绕“Qt软件安装demo示例”这个主题会覆盖三个最常见的需求在Windows和麒麟系统上从零把Qt环境装好并跑通一个最小demo。安装或运行demo时遇到 no qt platform plugin、找不到库、编译失败等问题如何高效定位解决。把跑通的demo打包成可分发软件Windows exe、Linux可执行文件让没有安装Qt的机器也能运行。如果你是刚接触Qt的新手按照我下面的顺序一步步走基本能避免掉大多数坑。如果你已经遇到报错可以直接跳到第4章看排查链路。2. 把Qt环境装明白Windows和麒麟Linux两套实操流程2.1 从哪里下载、怎么选版本、用什么加速Qt的下载渠道主要有两个官方安装器和国内镜像。官方下载地址是download.qt.io但国内直连速度不稳定而且新版安装器强制要求注册账号。我个人的建议是直接使用国内镜像站下载离线安装包或者在线安装器。常用的国内镜像有清华、中科大、阿里云具体用法大同小异。以清华镜像为例进入https://mirrors.tuna.tsinghua.edu.cn/qt/里面有archive和online_installers等目录。如果只是日常开发推荐选择一个稳定版比如Qt 5.15.2它有独立的离线安装包一次下载完整安装过程不需要联网后续出问题也容易排查。版本选择上我推荐新手学习/个人工具选择qt-opensource-windows-x86-5.15.2.exeWindows或qt-opensource-linux-x64-5.15.2.runLinux。5.15.2是最后一个开源离线安装包版本稳定教程多坑基本都被踩平了。需要处理高分辨率或新硬件可以尝试Qt 6系列但注意QCustomPlot等第三方库在Qt6下需要重新编译部分旧demo不一定兼容。下载时注意平台和位数。Windows下64位系统优先选x86_64别选成arm或macOS包。2.2 Windows下安装Qt的完整步骤与组件勾选建议打开安装器选择安装目录时不要有中文和空格我习惯放在D:\Qt或C:\Qt。组件选择界面是最容易出错的地方这里给一份针对“跑demo开发小工具”的最低配置展开Qt 5.15.2MinGW 8.1.0 32-bit和64-bit二选一即可但建议64位。MinGW套件自带编译器省得单独装。MSVC 2019 64-bit如果你以后可能用Visual Studio开发选上否则可以不选因为MSVC套件还需要你装VS Build Tools体积很大。Qt WebEngine等大模块除非demo明确需要否则先不选。展开Developer and Designer ToolsQt Creator必选。MinGW 8.1.0这个选项本质是编译器工具链如果你上面选了MinGW套件这里会一起带上。CMake 或 Ninja看情况跑cmake类demo时会用到建议选上。安装完成后打开Qt Creator在“工具→选项→Kits”里能看到自动检测到的套件。一个正常的套件应该包含编译器、qmake、平台。如果这里显示红色感叹号说明某个组件缺失后面的编译大概率会失败。我个人的经验如果只是为了快速跑通一个demo宁可在组件勾选上保守一点也不要为了省硬盘空间把一个套件里核心的“Sources”也去掉。Qt Sources在后续用qcustomplot等第三方库时需要用到虽然多数情况用不到但遇到问题再补齐很费时间。2.3 麒麟系统下通过命令行安装Qt的实操热搜词里有很多人搜“麒麟系统怎么安装软件”“银河麒麟安装软件命令”“qt离线安装 麒麟x86”。这里说清楚一个关键点麒麟桌面系统通常基于Linux内核自带apt/dpkg包管理器但默认源里不一定有你想装的Qt版本。而且麒麟系统大多是X86架构少数是ARMWindows下那套安装流程不适用。最稳妥的方式是下载Qt官方的qt-opensource-linux-x64-5.15.2.run离线安装包或使用国内镜像。但在执行前先确认几件事# 查看系统架构 uname -m # 查看系统版本 cat /etc/os-release如果是X86_64架构直接给.run文件加执行权限并运行chmod x qt-opensource-linux-x64-5.15.2.run ./qt-opensource-linux-x64-5.15.2.run安装器会有图形界面组件选择逻辑和Windows一致记得勾选对应系统架构的Desktop gcc 64-bit套件。如果你是完全命令行环境也可以使用Qt安装器的--script方式但手动图形安装已经够用。安装到只剩依赖库问题时可能会遇到类似libxcb-xinerama0、libxkbcommon-x11-0等缺失导致Qt程序无法启动。这是因为Qt在Linux下依赖一批X11的库。用apt直接补齐sudo apt update sudo apt install libxcb-xinerama0 libxkbcommon-x11-0 libxcb-cursor0 libgl1-mesa-dev libglu1-mesa-dev麒麟系统基于Debian/Ubuntu系这些包名通用。装完依赖后再启动。不过第4章还会专门讲xcb相关报错这里先按下。2.4 安装后必须做的三件事装完Qt你一定不能直接去双击别人的demo先做三个最小验证否则后面出问题全是虚惊验证qmake版本打开命令行Windows是cmd或PowerShellLinux是终端运行qmake -v。如果提示找不到命令说明没有把Qt的bin目录加入环境变量PATH。Windows下可以手动加Linux下用export PATH/opt/Qt5.15.2/5.15.2/gcc_64/bin:$PATH临时加长期加就写进~/.bashrc。创建空窗口测试在Qt Creator里新建一个Qt Widgets Application默认就一个空窗口点击运行。如果这个能弹出来说明你的开发环境基本是通的。确认构建套件激活Qt Creator左下角会显示当前使用的套件比如Desktop Qt 5.15.2 MinGW 64-bit。如果显示“No kit”或者灰色直接换一个套件再试。这三件事做完问题在于环境本身还是在于demo基本能判断个八九不离十。3. 写一个能跑的最小demo编译、运行、验证一条龙3.1 创建或导入demo工程时的常见选择假设你已经有一个网上下载的demo目录里面可能有.pro文件qmake工程也可能有CMakeLists.txtcmake工程。在Qt Creator中导入方式都一样打开文件选择.pro或CMakeLists.txt然后选择一套Kit。需要注意一个高频问题如果你的demo用到了第三方模块比如qcustomplot、串口模块、QtCharts你的Qt安装时如果没勾选对应模块编译时会报“Qt module not found”。比如QT serialport但你的组件里没有安装Qt Serial Port模块编译直接失败。解决方法就是在安装时补勾选模块或者使用在线安装器维护添加组件。对于需要自己加入的第三方库如qcustomplot通常把它的qcustomplot.h和.cpp拷贝到你的demo源码目录然后在.pro里加入QT widgets printsupport SOURCES main.cpp qcustomplot.cpp HEADERS mainwindow.h qcustomplot.h3.2 一个最小demo的完整代码示例自己动手写一个最简单的demo既能验证环境也能为后续扩展做准备。我平时测试环境就写一个带按钮和简单绘图的窗口用来验证Qt Widgets和QCustomPlot是否正常。先创建一个空项目新建文件或项目→其他项目→空qmake项目.pro文件内容QT core gui widgets TARGET qt_demo_test TEMPLATE app SOURCES main.cpp HEADERS main.cpp内容#include QApplication #include QMainWindow #include QPushButton #include QVBoxLayout #include QWidget int main(int argc, char *argv[]) { QApplication a(argc, argv); QMainWindow win; QWidget *central new QWidget(win); QVBoxLayout *layout new QVBoxLayout(central); QPushButton *btn new QPushButton(Hello Qt Demo, central); layout-addWidget(btn); central-setLayout(layout); win.setCentralWidget(central); win.resize(400, 300); win.setWindowTitle(Qt Software Installation Demo); win.show(); return a.exec(); }编译运行如果弹出带按钮的窗口说明您的基础Qt环境已经完好。这个demo虽然简单但“安装→编译→运行”的链路已经打通之后替换成复杂的绘图demo、串口demo都是在这个基础上增加模块。如果想在demo里加入时域图转频域图的示例网上相关教程非常多核心步骤是用QCustomPlot的.graph(0)-setData(x,y)传入时域数据再通过FFTkissfft得到频域幅值并重新传入绘图曲线。不过fft相关的第三方库需要额外引入建议先把基础demo跑通再扩展。3.3 编译链接过程中的高频报错与含义我收集了几个在群聊里被反复问的编译报错对应原因其实很明确报错信息实际原因解决办法Qt5Core.dll not found程序运行时找不到Qt库把Qt bin目录加入PATH或用打包工具部署cannot find -lGLLinux下缺少OpenGL开发库sudo apt install libgl1-mesa-devmainwindow.h: No such file or directorydemo引用的头文件路径不对检查.pro文件是否包含对应文件路径Project ERROR: Unknown module(s) in QT: serialport未安装serialport模块安装时勾选Qt Serial Port或重新运行在线安装器安装C1083: Cannot open include file: qcustomplot.h缺少第三方库头文件将qcustomplot的源文件和头文件加入工程其中unknown module in QT是最多的几乎每次demo跑不起来都是因为原作者用了一个你没装的模块。所以在下载demo前最好先看一眼它的.pro文件里QT 后面写了什么再反查自己安装的Qt里有没有对应模块。安装器里每个模块名字对应关系不是100%直观比如“Qt Charts”对应QT charts“Qt Serial Port”对应QT serialport。3.4 运行demo时最常见的两类崩溃编译能过运行就崩比编译不过更让人头疼。最常见的两类第一类是我开头说的no qt platform plugin could be initialized。这个崩溃本质是找不到平台插件咱们在第4章详细讲。第二类是双击exe没反应或者报The application was unable to start correctly。这通常是因为Qt的DLL缺失。比如在Windows下程序运行时需要Qt5Widgets.dll、Qt5Core.dll等但这些DLL路径不在系统PATH里所以找不到。解决办法是把Qt的bin目录临时加入PATH再运行或者后面统一用windeployqt打包。在Linux/麒麟下是你加了PATH也还缺xcb但逻辑类似。这两种归类到“运行时依赖问题”而不是代码问题所以不要纠结代码逻辑对不对先检查环境。4. no qt platform plugin can be initialized一次典型的安装后运行失败排查4.1 这个报错的本质和触发场景很多人会问明明Qt安装成功了Qt Creator里运行demo也没问题但为什么直接去双击构建目录里的exe就报no qt platform plugin could be initialized首先要理解这个报错是程序运行时发生的不是编译时。Qt程序在启动时会到可执行文件相邻目录的platforms文件夹里找平台插件。步骤如下程序读取当前目录或硬编码路径。查找platforms/qwindows.dllWindows或platforms/libqxcb.soLinux。如果找不到或者加载失败比如依赖的库缺失就报告这个致命错误。在Qt Creator里运行没问题是因为Qt Creator会自动把%QTDIR%/plugins目录加入搜索路径所以一切正常。当你直接运行exe时没有这个天然的环境设置自然就报错了。4.2 从报错到解决的完整排查链路我给其他小伙伴排查时基本是按下面这个顺序推进的。你自己遇到同样问题时也可以依序检查第一步确认exe旁边有没有platforms目录。在Windows下你在demo构建目录里运行exe前需要在exe同级的platforms目录下放qwindows.dll。如果你是把exe拷到别处运行那基本必中这个错误。第二步确认qwindows.dll的配件是否齐全。很多情况下刚把platforms目录复制过来还是会报错那是因为qwindows.dll本身依赖Qt的很多共享库如Qt5Gui.dll、Qt5Core.dll。这些库要么在exe同目录要么在PATH里。用windeployqt可以一次性把所有库正确部署不要去手动复制很容易漏。第三步检查是不是编译器版本冲突。同一个platforms目录下有多个版本的qwindows不明显但如果你用的是MinGW编译的demo却把MSVC版本的qwindows.dll复制过去也会加载失败。最简单的办法是先用Qt Creator跑通再在“构建目录”看Qt Creator自动生成的部署文件是否正常。第四步在Windows下还可以用容错模式来验证cd /d your_exe_dir set PATHD:\Qt\5.15.2\mingw81_64\bin;D:\Qt\5.15.2\mingw81_64\plugins;%PATH% D:\Applications\你的程序.exe如果设置了以上路径后程序能跑起来就说明是插件和库路径缺失的问题不是程序本身的问题。如果是Linux/麒麟系统排查时切换成export QT_DEBUG_PLUGINS1 ./your_app设置这个环境变量后Qt会在终端打印插件加载的详细日志能准确看到是找不到库文件还是某个依赖动态库加载失败比如Cannot load library /opt/Qt/plugins/platforms/libqxcb.so再附加symbol lookup error。4.3 手动修复复制插件目录还是设置环境变量如果是临时调试直接在环境变量里加上插件路径是有效果的# Linux/麒麟 export QT_QPA_PLATFORM_PLUGIN_PATH/opt/Qt/5.15.2/gcc_64/plugins但是注意这个环境变量只是“临时让程序找到插件”不代表打包时能带对。真正发布给别人的程序必须把plugins和lib目录以正确结构放在exe旁边。通常的做法是app/ ├── your_app.exe ├── platforms/ │ └── qwindows.dll ├── styles/ ├── imageformats/ └── ... 各种Qt DLLWindows下windeployqt会自动生成这个结构Linux下用linuxdeployqt完成类似工作。4.4 麒麟系统下的xcb依赖问题热搜词里频繁出现“银河麒麟安装软件命令”“qt离线安装 麒麟x86”说明不少人是在麒麟环境里折腾Qt。麒麟系统下跑Qt demo最典型的报错就是libqxcb.so加载失败。即便QT_QPA_PLATFORM_PLUGIN_PATH指向正确还是可能提示依赖缺失Failed to load platform plugin xcb. Available platforms are: xcb Cannot load library /opt/Qt/5.15.2/gcc_64/plugins/platforms/libqxcb.so这种问题的根源通常是系统缺少Qt所需的X11相关库。上文提到的libxcb-xinerama0、libxkbcommon-x11-0等就是其中几个。最好直接安装一批常用依赖sudo apt update sudo apt install libxcb1 libx11-6 libx11-xcb1 libxkbcommon0 libxkbcommon-x11-0 libgl1-mesa-dev libegl1-mesa libxcb-xinerama0 libxcb-cursor0 libxcb-icccm4 libxcb-image0 libxcb-keysyms1 libxcb-render-util0 libxcb-shape0 libxcb-xfixes0 libxcb-xkb1装完后重新运行Qt程序一般就能正常出现窗口。如果你是在麒麟系统上用命令行安装软件包记住apt是最常用的工具但不要随意更换系统源以免依赖版本错乱。5. 把demo变成可以发出去的软件打包发布的正确姿势5.1 为什么不能直接把exe拷给别人经常有人在群里发消息我编译好的exe大概10MB但是把整个目录拷给别人对方双击就报“缺少Qt5Core.dll”。原因是Qt程序是动态链接的10MB的exe只是你代码编译出来的体积它运行时要加载的Qt库动辄几十MB甚至上百MB。你需要把所有依赖的Qt模块DLL和插件一并带上。另外很多人只把bin目录里的DLL复制出来仍然会报platform plugin错误因为没有按插件目录结构摆放。这正是第4章问题的重演。5.2 Windows下用windeployqt打包的完整步骤用Qt自带的windeployqt工具可以自动扫描exe依赖的Qt模块并复制对应的DLL和插件到目标目录这是官方推荐的方式。在Qt命令行环境开始菜单里的“Qt 5.15.2 (MinGW 8.1.0 64-bit)”中执行cd /d D:\build\your_demo D:\Qt\5.15.2\mingw81_64\bin\windeployqt.exe your_app.exe执行完成后exe目录下会多出很多文件其中就包括platforms/qwindows.dll。还可以加参数指定额外模块比如你的demo用到了串口和Networkwindeployqt --network --serialport your_app.exe打包完成后把整个目录压缩发出去对方不需要安装Qt就能运行。不过我建议在本地测试时模拟一个干净环境先把当前环境变量中的Qt路径全部去掉再运行exe确认不依赖外部PATH。如果遇到工具提示Could not find qmake configuration多半是没有在Qt环境变量下运行。确保用的终端环境是从Qt Creator或Qt安装菜单启动的而不是普通cmd。5.3 Linux/麒麟系统下的打包思路Linux下没有官方一把梭的windeployqt社区常用的方案是使用linuxdeployqt工具但这个工具不是Qt官方出品针对不同发行版有时bug很多。我更推荐的稳妥做法是直接复制依赖库并写一个启动脚本。具体步骤假设你的demo二进制编译在/home/user/build/demo先把二进制复制到一个名为AppDir的目录。用ldd demo查看依赖的库路径把Qt相关的库比如libQt5Widgets.so.5复制到AppDir目录下。可以用脚本批量复制cp /opt/Qt/5.15.2/gcc_64/lib/libQt5Widgets.so.5 /home/user/AppDir/ cp /opt/Qt/5.15.2/gcc_64/lib/libQt5Gui.so.5 /home/user/AppDir/ cp /opt/Qt/5.15.2/gcc_64/lib/libQt5Core.so.5 /home/user/AppDir/ # 复制plugins/platforms mkdir -p /home/user/AppDir/platforms cp /opt/Qt/5.15.2/gcc_64/plugins/platforms/libqxcb.so /home/user/AppDir/platforms/编写一个启动脚本run.sh把LD_LIBRARY_PATH指向当前目录和Qt插件目录#!/bin/bash DIR$(dirname $(readlink -f $0)) export LD_LIBRARY_PATH$DIR:$DIR/platforms:$LD_LIBRARY_PATH export QT_QPA_PLATFORM_PLUGIN_PATH$DIR/platforms $DIR/demo授予执行权限后在目标机器上运行./run.sh即可。5.4 打完包还要做的验证清单我每次打包发给不同机器前都会走一遍这个验证清单少一项都可能被用户怼回来[ ] 在完全无Qt环境变量的终端或新用户下运行exe/可执行文件。[ ] 检查是否存在“no platform plugin”报错。[ ] 检查demo中用到的第三方库比如qcustomplot、fftw是否一并复制。[ ] 如果有中文路径确保程序安装路径不包含中文。[ ] 在麒麟系统或其他Linux发行版上测试一下缺少X11依赖时报错是否清晰必要时在启动脚本里自动检查并提示。这套流程做完你的demo才算真正从“自己电脑能跑”变成“别人也能跑”。6. 聊点还没提到但很实用的经验抛开具体命令Qt软件安装和demo跑通这件事说到底是一整套依赖管理的意识。很多人一味搜“qt demo 报错”却不去看.pro文件里的依赖、不去看plugins目录结构问题就总是复现。我自己踩过的最大的一个坑是为了省时间网上下载了一个所谓“绿色版Qt”结果编译器套件不完整导致后来所有demo都报Cannot find file: .pro白白折腾一整天。所以第一遍装Qt尽量用官方或清华镜像的完整离线安装包别用精简版。另一个我很少和别人提的细节安装Qt时MaintenanceTool其实是可以后期用来增删组件的。如果你最初少装了某个模块不需要重装整个Qt直接运行MaintenanceTool登录后选择“添加或移除组件”补勾选对应模块即可。很多人在群里问“qt的serialport模块怎么装”答案就是打开这个工具勾上再更新比重新下载安装包快得多。再有就是关于demo的本意。很多人拿到的“demo程序”往往是从网上拉下来的示例这类代码质量参差不齐用了老旧的Qt4语法或者依赖一个过时的第三方库。跑不通的时候先别怀疑是自己装错了先看版本兼容性。我最近遇到一个代码里写QString::toAscii在Qt5里根本没有这个函数所以编译就会报错。最好的处理方式是把这些代码改成Qt5/6的等价写法。最后说一个我自己的习惯我会在本地保留一个“最小demo模板”里面只有QMainWindow、一个按钮和一个QCustomPlot折线图。每次装完新的Qt环境或者帮别人检查环境问题我都先把这个模板跑一遍。如果模板能跑通就说明环境没问题问题出在对方的代码上如果模板都跑不通那就不用浪费时间看代码了。这个思路同样推荐给你能省下不少排查交互。本文还有配套的精品资源点击获取
