Qt安装全指南：版本选择、镜像加速与常见报错排查

“Qt安装”这四个字，看起来平平无奇，实际坑起来能让人怀疑人生。我见过太多人卡在第一步：官网下载几个小时超时、装完打开Qt Creator直接报qt.qpa.plugin: could not find the qt platform plugin "windows"、套件管理器里编译器全带黄色感叹号、Ubuntu上装完跑不起来提示缺xcb……其实这些坑，绝大多数都是安装阶段埋下的雷。这篇文章我就把Qt安装的完整流程、版本选择、国内镜像加速、Windows和Linux各自的关键步骤、以及安装后最常见的报错排查，一次性讲清楚。不管你是刚接触Qt的小白，还是准备换电脑重装环境的老人，照着做能少走很多弯路。

1. 动手安装前，先弄明白的三件事

安装Qt之前别急着点下载，先花五分钟想清楚三件事：装哪个版本、用什么编译器、从哪里下载。这三件事决定了你后面会不会踩坑。

1.1 版本选择：LTS、历史版本和Qt 6怎么选

Qt的版本号看着多，实际上当前场景下主要就几类选择。如果你要商用或者长期维护项目，认准LTS版本。所谓LTS就是Long Term Support，官方会长期维护、持续修bug。Qt 5系列的最后一个LTS是5.15.2，这个版本至今还有大量存量项目在用；Qt 6系列目前推荐6.5或6.8这类LTS版本，适合新项目直接上手。

那为什么很多人还在找5.12、5.14.2这些老版本？两个原因：一是老版本对旧系统兼容好，比如有些工业现场的Windows 7工控机，装Qt 5.12.12比新版本省心得多；二是有些第三方库、设备厂商SDK只适配到特定Qt版本，由不得你选。如果你没有兼容性包袱，直接选Qt 5.15.2或Qt 6 LTS即可。我自己的习惯是：新项目优先Qt 6.8 LTS，维护老项目就老实跟着项目走，别乱升级。

还要注意Open Source版和商业版的区别。个人学习、开源项目用Open Source版（LGPL协议）够了，功能上跟商业版基本没差，只是少了商业支持和部分高级模块。Open Source版安装时会让你勾选协议，选LGPL那一项就行。

1.2 编译器套件：MSVC还是MinGW

这是新手最容易懵的地方。Qt本身是一套C++库，它编译出来的程序要跟你的C++编译器配套。Qt官方在Windows上主要提供两套预编译包：

选MSVC还是MinGW，核心就看两件事：你有没有装Visual Studio，以及你的项目有没有依赖MSVC编译的第三方库。装了VS就用MSVC套件，这是最稳的组合；不想装VS这个庞然大物，就选MinGW套件，但要注意一点：MSVC和MinGW编译出来的二进制不能直接混用，动态库互换会崩。下载离线包的时候，可以把MSVC和MinGW都勾上，占不了多少空间，后续灵活切换。

1.3 下载渠道：国内用户的最优路径

Qt官网下载对国内网络不太友好，动不动就几KB/s。国内用户常用的加速方案是镜像站：

以清华镜像为例，路径是https://mirrors.tuna.tsinghua.edu.cn/qt/。进去后你会看到official_releases和online_installers等目录。离线安装包在official_releases/qt/下面，按版本号分目录，比如5.15.2就进5.15.2/，里面很多子目录，Windows安装包通常是qt-opensource-windows-x86-5.15.2.exe这样的名字。在线安装器在online_installers/目录，是一个很小但会联网拉组件的exe。

我的建议是优先下载离线安装包。在线安装器虽然能按需勾选组件，但国内网络下经常下载到一半断掉，断了又要重新校验。离线包一次下载整个版本，之后安装就是本地操作，甚至可以拷贝到没网的机器上部署，省心太多。

2. Windows环境下的Qt安装全流程

Windows是Qt开发最大的用户群，也是坑最多的地方。这一节我把完整流程拆开讲，按步骤操作基本不会出问题。

2.1 离线安装包的下载与文件校验

从镜像站下载完离线包后，别急着双击安装。先做两件事：确认文件完整性和确认系统位数。Qt安装包区分x86和x86_64，现代机器基本都是64位系统，下载时认准文件名里的x86_64或x86_64字样。少数工业现场的老机器还是32位，才需要x86版本。

文件完整性校验用哈希值。镜像站一般会提供一个.sha256或.md5文件，下载后打开PowerShell执行：

Get-FileHash .\qt-opensource-windows-x86-5.15.2.exe -Algorithm SHA256

对比输出和镜像站提供的哈希值，一致再安装。这一步看着麻烦，但能避免下载损坏导致安装一半报错。我实测过好几次，镜像站高峰期下载的包偶尔会出现校验失败，重下一次又好了，都是网络抖动导致的。

2.2 组件勾选与安装路径规划

安装包启动后，一路下一步到组件选择页面。这里有几个原则：

• 如果走MSVC路线，展开Qt 5.15.2，勾选MSVC 2019 64-bit；如果走MinGW路线，勾选MinGW 8.1.0 64-bit。两者可以同时勾，不会冲突。
• 语言和附加模块按需勾。常用的是Qt Charts（图表）、Qt Data Visualization（三维数据可视化）、Qt Multimedia（音视频模块）、Qt SerialPort（串口通信）。别贪心全选，很多模块你用不上，白白占掉几个G的硬盘空间。
• 展开Developer and Designer Tools，确保勾选Qt Creator和Qt Creator Debugger。CMake和Ninja建议勾上，后面很多项目构建要用，省得单独装。
• Sources组件（源码包）按需，一般不需要勾。只有要调试到Qt库内部时才需要。

安装路径这一条，强烈建议直接装到根目录下，比如C:\Qt。路径中不要有中文、空格、特殊符号。你永远不知道哪个老掉牙的工具会在含空格的路径上发疯。我自己统一用D:\Qt\Qt5.15.2这种风格，盘符随意，但路径一定要干净。

安装过程就是等待，正常情况下5到10分钟。如果安装时报错中断，优先怀疑下载的包不完整，回到2.1的哈希校验重新下载。

2.3 Qt Creator套件检测与配置

安装完成后打开Qt Creator，首次启动会自动检测已安装的Qt套件。你在“工具-选项-Kits”里应该能看到类似Qt 5.15.2 MSVC2019 64bit和Qt 5.15.2 MinGW 8.1.0 64bit的条目。如果套件显示黄色感叹号，说明编译器或调试器没识别全，通常是缺VS或者缺Debugger工具，按提示补装对应组件即可。

这里涉及一个环境变量问题。很多教程让你手动加QTDIR和PATH，实际上如果只用Qt Creator，它内部能够自动定位，不加环境变量也能正常编译。但如果你要命令行编译、或者写脚本调用qmake，环境变量就必须配好。推荐配置方式：

QTDIR=D:\Qt\Qt5.15.2\5.15.2\msvc2019_64 PATH=D:\Qt\Qt5.15.2\5.15.2\msvc2019_64\bin;%PATH%

注意QTDIR一定要指向你实际使用的套件目录，不是安装根目录。装了MinGW和MSVC两套时，环境变量只能指向其中一套，所以如果你主要用Qt Creator图形界面开发，我反而建议不要设环境变量，避免两套库混用产生“找到头文件版本不对”的玄学问题。

2.4 从新建项目到第一个窗口程序

套件配置好后，建议立刻跑一个工程验证。点击“新建项目”，选择Qt Widgets Application，编译套件选跟你环境对应的那条。跑通之后验证一下qmake是否正常，在Qt Creator的“工具-外部-命令行工具”里打开命令提示符，或者直接开系统终端执行：

qmake -v

能输出Qt版本信息，说明整套环境已经通了。接下来就可以创建你的第一个窗口程序了，界面拖几个控件、写一句qDebug()打印，编译运行。很多人在这一步卡住，编译时提示找不到头文件，十有八九是套件选错了，比如Qt是MSVC编译的，但你选了MinGW套件，Qt Creator还没自动切换编译器，两种工具链混着用，立刻报错。

3. Ubuntu系统搭建Qt开发环境

Windows之外，Linux也是Qt的重要场景，尤其嵌入式开发、服务器端无界面程序。Ubuntu是代表性的发行版，我以它为例讲透两种安装路线。

3.1 两种安装方式怎么取舍

Linux上装Qt无非两条路：一是系统apt源直接安装，二是用Qt官方在线安装器装到用户目录。这两路各有优劣：

• apt源安装：一句话就能装好，跟系统包管理统一，升级方便。缺点是版本往往偏老，比如Ubuntu 22.04源里的Qt通常不是最新版，而且没有官方在线安装器里那些细分的模块包。
• 官方在线安装器：版本新、模块全，可以选装Qt Charts这类附加库。缺点是要联网下载，而且在线安装器是图形界面，在纯服务器上还得想办法绕过。
• 另外还有一条路是下载Linux平台的离线安装包，跟Windows离线包类似，优点是可在无网或内网环境安装。

我的建议：如果你只是要一个能编译运行Qt的环境，apt源够了；如果你需要指定版本、特定模块，或者要为嵌入式交叉编译做准备，用官方在线安装器。

3.2 apt源安装与依赖处理

用apt安装Qt相当简单：

sudo apt update sudo apt install qtbase5-dev qtchooser qt5-qmake qtcreator qtbase5-dev-tools

qtbase5-dev是Qt 5的基础开发包，包含了核心库和头文件；qtchooser用于切换Qt版本；qtcreator是IDE；qtbase5-dev-tools提供qmake等命令行工具。如果要跑Widgets图形程序，还需要一个关键依赖：

sudo apt install libgl1-mesa-dev libfontconfig1-dev libdbus-1-dev

libgl1-mesa-dev尤其重要，qt的OpenGL相关模块必须要它，不装会在链接时报一堆奇怪的undefined reference。装完检查一下：

qmake -v

能正常输出版本号，环境就通了。命令行编译一个最简单的工程：

qmake -project qmake make

生成的可执行文件如果在无图形界面的服务器上跑，记得加-platform offscreen参数，不然会报找不到xcb platform插件。这一点在后续部署时很常见。

3.3 在线安装器的Linux注意事项

如果选择官方在线安装器，从官网或镜像站下载Linux版后，先给执行权限：

chmod +x qt-online-installer-linux-x64-*.run

直接运行通常会报缺少xcb库，界面闪退。这是因为图形界面依赖一堆X11开发库，在线安装器本身也是Qt程序。需要先装依赖：

sudo apt install libxcb-xinerama0 libxcb-cursor0 libxkbcommon-x11-0 libgl1-mesa-dev

装完再运行安装器，就能正常弹出图形界面了。如果还是报qt.qpa.plugin: could not load the Qt platform plugin "xcb"，八成是缺了上述某个库，用ldd检查一下插件文件依赖：

ldd /home/user/Qt/5.15.2/gcc_64/plugins/platforms/libqxcb.so

看输出里哪个库显示not found，补装对应的libxcb-*-dev包即可。装的过程里，安装器会要求你登录Qt账号。没有账号就现场注册一个。有人说现在在线安装器强制登录，离线安装包则不需要，这也算离线包的一大优势。

3.4 交叉编译与嵌入式环境的初步准备

很多人在Ubuntu上搭Qt，最终目的是做嵌入式交叉编译，比如给ARM板子编译程序。这种场景，本机的Qt套件其实只是工具链的一部分，最关键的是安装交叉编译器。比如用gcc-aarch64-linux-gnu，然后到Qt Creator里添加一个新的Kit，配置对应的编译器和qmake路径。这一套流程虽然不属于基础安装，但我要提醒一句：千万别试图在Ubuntu主机上直接跑ARM目标板的程序，目标板库和主机库不兼容，装完基本就是白折腾。正确做法是主机装Qt用于开发调试，目标板烧录带Qt库的交叉编译文件系统，程序编译好之后拷贝过去运行。

4. 麒麟等国产Linux系统上的Qt安装要点

除了Ubuntu，国内很多单位会用到麒麟这类基于Debian或CentOS桌面的Linux发行版。它们虽然界面接近Ubuntu，但依赖库版本、包管理器细节都有差异，动辄就会出幺蛾子。这里讲几个高发问题和解法。

4.1 在线安装器在受限系统上的表现

麒麟系统默认环境下，直接运行Qt在线安装器经常遇到两个问题。一是图形界面起不来，报错的本质还是缺平台插件，但因为有的时候系统自带的源里没有对应依赖包，用apt install装不上，就需要用--no-xcb之类的环境变量先绕过：在终端里设置QT_QPA_PLATFORM=offscreen再运行安装器，让它能在无图形环境下用命令行模式安装。实际上安装器支持静默安装，参数大致是：

./qt-online-installer-linux-x64.run --platform offscreen --accept-licenses --default-answer --accept-obligations --confirm-command install com.qt.qt5.15.2.gcc_64

这种方式在图形界面和权限受限的机器上都能跑，装完组件到用户目录，再手动配置Qt Creator。不过静默安装有个坑：它默认只装基础模块，附加模块要在命令行参数里逐个指定，比如加com.qt.qt5.15.2.addon.charts才能装Qt Charts。

4.2 运行库缺失与platform插件的修正

装好Qt后在麒麟系统上运行程序，最常见报错就是qt.qpa.plugin: could not load the Qt platform plugin "xcb"。这个错误在绝大多数Linux发行版上都能看到，原因是Qt程序启动时需要加载libqxcb.so这个平台插件，往deep里说，它依赖XCB库、X11库、xkbcommon等一系列东西，缺一个就全线崩溃。排查套路固定：先看程序启动时的完整报错，再定位plugins/platforms/目录是否存在，最后用ldd查缺失依赖。

在麒麟这种包管理器不一定齐全的系统上，我一般先查系统里有没有libxcb-xinerama0，没有就从源里或者编译源码装。装齐后用环境变量强制指定插件路径：

export QT_QPA_PLATFORM_PLUGIN_PATH=/opt/Qt/5.15.2/gcc_64/plugins/platforms

很多时候直接就能解决。这个方法也适用于各种ARM版本的国产系统，因为路径明确、不依赖包管理器。

4.3 离线包在存量系统的兼容性处理

如果目标机器网络受限、或者拿到的是安装了老版本依赖库的存量系统，我强烈建议走离线安装包路线。离线包体积大，但安装时不联网、不登录、不依赖安装器仓库，装上就能用。安装过程中如果提示缺少某个库，用包管理器补装对应的libxcb*、libgl1-mesa-dev即可。

还有一点：跑在服务器上的麒麟系统，没有桌面环境时，别想着启动任何带界面的Qt程序。要么确认装了桌面，要么老老实实设QT_QPA_PLATFORM=offscreen让它后台运行，这部分我在部署无界面服务时已经验证过多次，别浪费时间跟平台插件死磕。

5. 装完必看的常见问题与排查方法

Qt安装本身不难，但装完之后你大概率会遇到几个经典问题。这些问题不是我编的，是大量读者和身边朋友问过我无数遍的真实案例。

5.1 启动报错：qt.qpa.plugin找不到platform plugin "windows"

这条报错应该是Windows上出现频率最高的一条，完整文字是qt.qpa.plugin: could not find the Qt platform plugin "windows" in ""，后面还跟着一句This application failed to start because no Qt platform plugin could be initialized.。我第一次遇到时也抓狂，后来总结下来，原因基本就是三类。

第一类，程序运行时没找到qwindows.dll这个平台插件。它位于Qt安装目录的plugins\platforms\下。程序发布时如果只拷贝了exe和dll，忘了把plugins整个目录带过去，就会报这个错。第二类，环境变量没设置，程序通过PATH找不到Qt的bin目录，进而定位不到plugins，尤其在你把exe复制到别的地方运行时最常见。第三类，路径里有中文、空格或者杀毒软件乱删文件，让qt库加载链断掉了。

排查时先看你的exe旁边有没有platforms\qwindows.dll，没有就从C:\Qt\Qt5.15.2\5.15.2\msvc2019_64\plugins\platforms\复制过去。再检查系统环境变量PATH里是否包含Qt安装目录\版本号\套件\bin，没有就加上。最后，设置一个临时变量手动指定插件目录：

set QT_QPA_PLATFORM_PLUGIN_PATH=C:\Qt\Qt5.15.2\5.15.2\msvc2019_64\plugins\platforms

设置之后再次启动，如果正常，说明就是插件路径问题。发布正式程序时，不要手工拷贝插件，用Qt自带的部署工具最稳妥。Windows上用windeployqt.exe：

windeployqt.exe your_app.exe

它会把需要的dll和plugins自动归拢到exe同目录，这才是正式发布的标准姿势。

5.2 编译器套件显示黄色感叹号或找不到编译器

Qt Creator里打开“工具-选项-Kits”，如果某个套件显示感叹号，优先检查的是编译器那一栏是否为空。MSVC套件要求系统装了对应版本的Visual Studio或者Build Tools；MinGW套件只需要Qt安装包自带MinGW编译器，但是套件里的“编译器”路径要指向qtools\mingw810_64\bin\g++.exe这类位置，如果在自定义安装Qt时没把MinGW工具链勾上，套件自然找不到编译器，感叹号就亮了。

处理方案：打开安装目录下的MaintenanceTool.exe，选择“添加或移除组件”，把缺失的MinGW或者调试器补装上。很多教程让新手重装Qt，其实就是没用好这个维护工具。注意，如果你用的是MSVC套件，又不想装完整版VS，可以去微软官网下载安装Build Tools for Visual Studio，体积小得多，完全可以满足编译需求。装完重启Qt Creator就能识别到。

5.3 正确卸载Qt：别直接删文件夹

卸载Qt这件事，顺手就删掉C:\Qt文件夹的人不在少数，结果就是注册表残留、开始菜单残留、下次重装还会莫名其妙报错。正确的卸载方式：进入Qt安装根目录，找到MaintenanceTool.exe，运行后选择“移除所有组件”。它会调用卸载器清理安装项，再把残留的目录删掉。这一步做完，有余力的可以把系统环境变量里的QTDIR和PATH里Qt相关条目一并清理，注册表项HKEY_CURRENT_USER\Software\QtProject也可以检查删除。

如果你是apt装的Linux Qt，卸载命令则是对应的sudo apt remove qtbase5-dev qtcreator。别混用，Windows的卸载工具在Linux上用不了，反之同理。

5.4 一批高频小问题速查

这张表里最后一条想多说两句。很多人在程序崩溃时面对一屏乱码，第一反应是找代码问题，却忽略了自己的Qt环境可能没安装调试符号。装Qt时勾上Qt Debug Symbols，再用windeployqt --debug部署，崩溃时能看到更详细的调用栈，排查效率完全不同。

最后分享一点个人经验

算下来，我自己在Windows、Ubuntu、各种Linux发行版上装Qt的次数少说也有几十回，最深的体会就是：安装这种事，选择比努力重要。版本选对了、套件选匹配了、镜像选国内了，整个安装过程可以十分钟内结束；反过来，官网硬啃、组件乱勾、MSVC和MinGW混用，后面编译报错的时间和精力远远超过安装本身。另一条经验是，别把环境变量当成万能的，能靠Qt Creator自动管理就让它自动管理，非要手配环境变量时，认准套件目录，别配成安装根目录。最后，安装完务必跑通一个真实验证工程，不要只看到qmake -v输出就以为万事大吉。凡事多留个心眼，把windeployqt这个部署工具练熟，后续发布到其他机器就不会被qt.qpa.plugin这种低级错误折磨了。