企业官网建设流程全解析

简介：面向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是IDE，qmake是构建工具，还有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示例”这个主题，会覆盖三个最常见的需求：

1. 在Windows和麒麟系统上，从零把Qt环境装好，并跑通一个最小demo。
2. 安装或运行demo时遇到 no qt platform plugin、找不到库、编译失败等问题，如何高效定位解决。
3. 把跑通的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.exe（Windows）或qt-opensource-linux-x64-5.15.2.run（Linux）。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.2：
  • MinGW 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 Tools：
  • Qt 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架构，少数是ARM，Windows下那套安装流程不适用。

最稳妥的方式是下载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，先做三个最小验证，否则后面出问题全是虚惊：

1. 验证qmake版本：打开命令行（Windows是cmd或PowerShell，Linux是终端），运行qmake -v。如果提示找不到命令，说明没有把Qt的bin目录加入环境变量PATH。Windows下可以手动加，Linux下用export PATH=/opt/Qt5.15.2/5.15.2/gcc_64/bin:$PATH临时加，长期加就写进~/.bashrc。
2. 创建空窗口测试：在Qt Creator里新建一个Qt Widgets Application，默认就一个空窗口，点击运行。如果这个能弹出来，说明你的开发环境基本是通的。
3. 确认构建套件激活：Qt Creator左下角会显示当前使用的套件，比如Desktop Qt 5.15.2 MinGW 64-bit。如果显示“No kit”或者灰色，直接换一个套件再试。

这三件事做完，问题在于环境本身还是在于demo，基本能判断个八九不离十。

3. 写一个能跑的最小demo：编译、运行、验证一条龙

3.1 创建或导入demo工程时的常见选择

假设你已经有一个网上下载的demo目录，里面可能有.pro文件（qmake工程），也可能有CMakeLists.txt（cmake工程）。在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.h

3.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)传入时域数据，再通过FFT（kissfft）得到频域幅值并重新传入绘图曲线。不过fft相关的第三方库需要额外引入，建议先把基础demo跑通再扩展。

3.3 编译链接过程中的高频报错与含义

我收集了几个在群聊里被反复问的编译报错，对应原因其实很明确：

其中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文件夹里找平台插件。步骤如下：

1. 程序读取当前目录或硬编码路径。
2. 查找platforms/qwindows.dll（Windows）或platforms/libqxcb.so（Linux）。
3. 如果找不到，或者加载失败（比如依赖的库缺失），就报告这个致命错误。

在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 PATH=D:\Qt\5.15.2\mingw81_64\bin;D:\Qt\5.15.2\mingw81_64\plugins;%PATH% D:\Applications\你的程序.exe

如果设置了以上路径后程序能跑起来，就说明是插件和库路径缺失的问题，不是程序本身的问题。

如果是Linux/麒麟系统，排查时切换成：

export QT_DEBUG_PLUGINS=1 ./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 DLL

Windows下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用到了串口和Network：

windeployqt --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很多。我更推荐的稳妥做法是：直接复制依赖库，并写一个启动脚本。

具体步骤：

1. 假设你的demo二进制编译在/home/user/build/demo，先把二进制复制到一个名为AppDir的目录。
2. 用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/

3. 编写一个启动脚本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环境，或者帮别人检查环境问题，我都先把这个模板跑一遍。如果模板能跑通，就说明环境没问题，问题出在对方的代码上；如果模板都跑不通，那就不用浪费时间看代码了。这个思路同样推荐给你，能省下不少排查交互。

本文还有配套的精品资源，点击获取