从来没有哪个开源框架的安装过程能让这么多人集体卡壳Qt绝对是独一份。你说它难吧下一步下一步就完事了你说它简单吧社交平台上一搜Qt安装大把人在组件选择那一步翻车。最常见的剧本就是装的时候顺手全点了硬盘爆掉或者图省事一路默认结果项目编译时甩给你一句Project ERROR: Unknown module(s) in QT: serialport当场傻眼。这篇文章不打算重复官网那份枯燥的安装向导说明我直接把组件选择界面从里到外拆开讲透每个分组是干什么的、哪些必选、哪些按需、哪些选错会埋雷以及装完之后怎么验证、怎么补救。内容基于我这些年用 Qt 5.12 / 5.14 / 5.15.2 做桌面客户端和嵌入式工具的实际经验照着勾基本不会出错。1. 为什么Qt装完老出幺蛾子:组件筛选才是安装的关键很多人的直觉是安装软件嘛能勾的全勾上功能最全肯定没错。这个思路放在普通软件上勉强成立放在 Qt 上就是灾难。一个全量勾选的 Qt 5.15.2 在线安装体积能轻松突破 30GB更离谱的是里面大量内容你根本用不上比如针对 Android、iOS、WebAssembly 的交叉编译套件。装完之后磁盘占用巨大编译的时候还要面对几十个编译套件来回切换的混乱局面。组件筛选的本质是搞清楚两件事你用 Qt 干什么以及你在什么平台上干。只写 Windows 桌面程序那你就只需要一个桌面编译套件MinGW 或 MSVC外加 Qt Creator 编辑器。要打包发布、写安装程序那可能需要 Qt Installer Framework或者额外下个 Inno Setup 之类的外部工具。要用串口、网络、数据库、图表这些功能对应的模块必须在安装时勾选否则代码里#include QtSerialPort或者QT serialport直接给你报错。要调试 Qt 源码就离不开 Sources 组件要定位 Qt 自身崩溃需要 Qt Debug Information Files。说白了组件选择的本质就是按需装配。选多了浪费磁盘和编译时间选少了后面各种unknown module报错两头都难受。这篇文章就是把需求和组件之间的对应关系捋清楚。另一个需要注意的地方是组件选择界面里经常出现一半打勾、一半空白的复选框这个叫部分选择表示该分组下有部分子项被选中。很多人看到这个灰色勾以为选上了实际漏装了一堆东西。后面我会专门说这种复选框怎么处理。2. 动手装之前,先把这三个问题想清楚在进入组件选择界面之前有三个前置问题必须确认不然选组件时你根本不知道该选哪个版本、哪个编译器。很多人上来就默认结果装完发现编译器不匹配又得重来非常浪费时间。2.1 用在线安装器还是离线安装包这是第一个岔路口。在线安装器qt-online-installer是一个体积只有几十MB的小程序运行时按需下载组件好处是灵活、可以断点续传、后续能随时用维护工具增删组件。缺点也很明显国内网络环境下下载速度很感人几十GB的依赖能挂一整晚。离线安装包则是把所有组件打包成一个巨大的安装文件单个 .run 或 .exe常见有 3GB 到 8GB 不等好处是一次下载、离线安装、可重复使用坏处是安装时不能自定义选择组件版本且后续没办法用维护工具添加新组件有的离线包可以有的不行。如果你有拷贝到内网机器上安装的需求离线包是唯一选择。从热搜词里也能看到qt离线安装包下载5.14这种具体需求说明很多人是要装内网环境或者特定版本。我的建议是个人开发、网络条件差用离线包选一个接近自己需求的版本一口气装完。团队协作、可能增减模块在线安装器 维护工具后续按需调整。2.2 编译器套件决定上限选组件前先想明白你打算用什么编译器。Qt 组件的安装列表里一个版本下面通常会有MinGW 64-bit / 32-bitGCC 的 Windows 移植版开源、随装随用不依赖 Visual Studio。MSVC 2019 / 2022 64-bit微软的 Visual C 编译器需要电脑上装对应版本的 Visual Studio 或 Build Tools。UWP做 Windows 商店应用才需要普通人碰都不用碰。Android / iOS / WebAssembly跨平台移动端和应用纯桌面开发直接跳过。这两类编译器选哪个直接决定你后面用的是mingw32-make还是nmake编译出来的依赖库也不互通。比如你用 MinGW 编译的程序想链接一个 MSVC 编译的第三方 DLL大概率出现符号冲突、链接失败。所以安装时只选一个主用编译器就够了最多加个备用别把 MinGW 和 MSVC 全装上后面切来切去容易混乱。2.3 Qt 版本不是越新越好Qt 6 已经出了好几年但不少老项目、旧依赖库还趴在 Qt 5 上这也是Qt 5.15.2 下载安装这类关键词长期霸榜的原因。Qt 5.15 是 Qt 5 系列的最后一个 LTS长期支持版本社区生态最成熟第三方库基本都能找到对应版本新学 Qt 或者维护老项目选 5.15.2 最稳。如果你是新项目、从零开始Qt 6 的 CMake 集成更现代、对高分辨率屏支持更好也是不错的选择。但注意Qt 6 的组件列表和 Qt 5 差异比较大一些模块被拆分或合并了这篇讲到的组件对照逻辑同样适用具体模块名要按你安装版本的实际情况来。这里有个经验值可以参考选版本时最好查一下它配套的 Qt Creator 和编译器版本要求三者匹配才能跑得顺。安装器通常会默认选好匹配的 Qt Creator但如果你在安装器里手动取消了后面再单独装 Creator版本和 Qt 库不匹配时会出现在套件页面里找不到编译套件或者识别不到 Qt 版本的情况。3. 组件选择界面逐项拆解:哪些必选,哪些按需,哪些别碰现在进入正题组件选择界面长什么样、每一项到底是什么意思。以 Qt 5.15.2 在线安装器为例左侧是层级列表主要有Qt、Tools、Developer and Designer Tools三大类。下面逐个拆。3.1 Qt 主分类下的核心模块展开Qt节点你能看到一堆版本条目Qt 5.15.2、Qt 6.2.x等。展开某个版本后里面还有细分的子组件。注意这些子组件不是靠嘴说选的它们是真正要下载的库文件、源码头文件和构建工具。MinGW 8.1.0 64-bit或类似的 MinGW 条目这是你实际编译链接时要用到的 Qt 库比如 Qt5Core.dll、Qt5Widgets.dll、Qt5Gui.dll。选它等于把Windows 桌面 MinGW 编译器这一套完整编译环境拉下来。一个版本下有 MinGW 和 MSVC 两种库我的建议是先确定编译器再选对应的 Qt 库别全选。MSVC 2019 64-bit同样是 Qt 库只是编译工具链换成了 MSVC。如果你用 Visual Studio 开发插件或者想用某些只提供 MSVC 版本的第三方库就选它。前提是你机器上已经装了 Visual Studio 2019或对应版本否则 CMake/qmake 都识别不到套件。UWP这是专门给 Windows 通用应用平台准备的普通桌面开发完全用不上。选上只会白白多出几个G的下载内容而且编译目标会多出不少让你困惑的选项。跳过。SourcesQt 的源代码包。平时写代码、断点调试时如果你希望按 F11 能直接进入 Qt 源码内部看实现逻辑就必须装它。否则调试时看不到 Qt 内部调用链只能看到汇编或Source not found。我的个人习惯是只要硬盘够Sources 必勾。查一个信号从发射到槽函数执行的完整链路时源码是最权威的参考资料比网上搜到的二手教程靠谱太多。Qt Debug Information Files这个组件对应 Qt 库的 PDB 调试符号文件。程序崩溃时它能帮你把堆栈信息映射到具体的 Qt 函数名而不是一串十六进制地址。用 MinGW 时不是必须的但用 MSVC 调崩溃问题有这个和没有完全是两种排查体验。磁盘空间允许就勾上。Qt Charts、Qt Data Visualization、Qt WebEngine、Qt Serial Port 等模块这些是 Qt 的功能模块扩展对应你项目的具体需求模块用途什么时候需要勾Qt Charts折线图、柱状图、饼图等图表要画数据曲线、做仪表盘界面时Qt Data Visualization3D 数据可视化三维散点、曲面图等场景Qt WebEngine内嵌 Chromium 浏览器内核在界面里显示网页、HTML 内容时Qt Serial Port串口通信库做下位机调试工具、硬件通信Qt Network网络通信默认包含在核心库中绝大多数项目都需要尽量保持Qt Multimedia音频、视频播放和采集做播放器、音视频处理Qt SQL数据库驱动SQLite、MySQL、PostgreSQL 等需要连数据库时Qt ActiveXCOM 和 ActiveX 支持需要调用 Windows 自带 COM 组件或做 Office 集成这里要特别强调Qt 的模块勾选状态直接决定后面 qmake 的.pro文件里能不能写QT serialport。如果没勾光在.pro里加这句编译时就会报出热搜词里那个经典的错误Project ERROR: Unknown module(s) in QT: serialport。我后面会专门说这个怎么补。3.2 Tools 分类下的辅助工具Tools节点平时很多人忽略里面装着编译和开发必需的外围工具。Qt CreatorQt 官方 IDE你必须装。里面还可能分Qt Creator和Qt Creator Plugin Development两个子项后者是开发 Qt Creator 插件才需要的普通用户选前者即可。MinGW / MSVC 工具链在线安装器会帮你把 MinGW 的编译器gcc.exe、g.exe、mingw32-make.exe下下来并配好路径。如果你轨道上选了Qt 5.15.2下的MinGW 8.1.0 64-bit这里通常会自动带出对应的MinGW 8.1.0条目保持默认勾选即可。注意把 Qt 库和编译器分开列很多人以为勾了 Qt 库就够编译了实际上是两回事。Qt 库是编译链接时的依赖库MinGW 是编译器本身两个缺一不可。只勾库不勾编译器装完后打开 Qt Creator 会发现套件不完整编译按钮是灰的。CMake、Ninja如果你打算用 CMake 构建系统写 Qt 6 或现代 Qt 5 项目这两个是标配。Qt 5.15 的 qmake 不需要 CMake但很多第三方库和范例都转向 CMake 了装一下不亏。磁盘空间通常也很小。3.3 Developer and Designer Tools 分类多数人用不上这个分类下是Qt 3D Studio、Qt Design Studio这类偏设计工具的东西。Qt Design Studio 是给 UI/UX 设计师用的用来做动态界面交互设计和过渡动画。普通程序员用不到也不建议装它和 Qt Creator 的定位完全不同装上只会让安装列表更乱。3.4 勾选策略的参考模板根据不同需求我整理了一份可以直接抄作业的勾选组合以 Qt 5.15.2 为例使用场景必选组件可选/建议勾选千万别碰桌面小工具串口、网络对应版本的 MinGW 或 MSVC 库、Qt Creator、编译器工具链Sources、Qt Serial Port、Qt ChartsUWP、Android、WebAssembly跨平台桌面应用各目标平台的库、CMake、NinjaSources、Qt Network、Qt WebEngine不需要冗余的编译套件嵌入式/HMI 界面对应交叉编译工具链、Qt Quick、Qt Quick ControlsQt 3D、Data Visualization别在工作机装全套桌面库数据可视化应用对应桌面库、Qt Charts、Qt Data VisualizationSourcesUWP、移动端套件4. 漏选组件的代价与补救:serialport 报错的完整排查链路组件没勾对最常见的下场就是编译报错。我写过很多串口调试工具这块的坑踩得最多。顺着热搜词里的qt unknown module in qt:serialport和unknown module(s) in qt: serialport我把完整的排查链路和补救方法讲清楚。4.1 报错是怎么来的假设你的.pro文件里有一行QT core gui serialport或者你在CMakeLists.txt里写了find_package(Qt5 REQUIRED COMPONENTS SerialPort)编译时qmake 或 CMake 会去 Qt 安装目录里找对应的模块文件。如果安装时没勾选 Qt Serial Port 模块Qt5SerialPort.dll和对应的 cmake 配置文件根本不存在于是编译器直接报Project ERROR: Unknown module(s) in QT: serialport这个报错的迷惑性在于你的代码逻辑完全没问题问题出在安装环节。没有经验的人会反复检查代码、检查.pro格式甚至重装整个 Qt浪费大量时间。4.2 确认问题根源的三步验证法碰到这个报错先别急着重装按下面三步确认第一步查看 Qt 安装目录里有没有串口模块。找到你安装的 Qt 路径比如C:\Qt\5.15.2\mingw81_64进去看lib目录下有没有cmake\Qt5SerialPort这个目录以及bin目录下有没有Qt5SerialPort.dll。没有那就是没装这个模块。第二步用 qmake 命令行查当前 Qt 支持的模块列表# 进入 Qt 的 bin 目录 cd C:\Qt\5.15.2\mingw81_64\bin # 查看 Qt 路径配置 qmake -query QT_INSTALL_PREFIXQT_INSTALL_PREFIX会告诉你当前编译套件实际使用的 Qt 根目录确认模块缺失发生在哪一个安装实例上。如果电脑上装了多个 Qt 版本这一步能帮你定位到底用的哪一份库。第三步打开 Qt Creator 的选项 → 套件检查当前套件对应的 Qt 版本路径。有时候.pro文件里没写错但 Qt Creator 自动选择的套件指向了另一个没装串口模块的 Qt 安装目录导致同样的代码换个套件就能编译。这一步很常见也最容易被忽略。4.3 补救方式一:用维护工具补装组件Qt 在线安装器装出来的环境自带一个MaintenanceTool.exe在安装目录的根目录下。运行它选择添加或移除组件然后重新进入组件选择界面找到对应版本的Qt Serial Port勾上点下一步等待下载安装即可。补装完重新打开 Qt Creator报错就会消失。这套操作也适用于其他漏装的模块比如Qt Charts、Sources原理一致。离线安装包版本的 Qt 没有维护工具遇到漏装就麻烦了要么重新下载一个更全的离线包要么从其他机器拷贝对应模块文件到安装目录。我自己遇到过用离线包装完才发现漏了 WebEngine最后是找了一台装了同款 Qt 的机器把整个 WebEngine 相关文件拷贝过来才算解决。强烈建议内网用户记一下自己装的组件清单避免来回折腾。4.4 补救方式二:没有维护工具时的手术刀式补装对于离线包或已经删掉安装器的环境补装本质上就是缺什么文件就补什么文件。以串口模块为例你需要从同版本、同编译器套件的 Qt 安装目录里拷贝lib目录下带SerialPort的.lib、.a、.prl、.dll文件include\QtSerialPort整个头文件目录lib\cmake\Qt5SerialPort整个 CMake 配置目录mkspecs\modules下的qt_lib_serialport.pri部分版本有。如果你手头有一台装了完整版 Qt 的电脑远程拷贝或者 U 盘都行。拷贝完记得清一下 CMake 缓存或者 qmake 缓存否则可能因为缓存不一致还是报错。这个方法不仅能补串口理论上 Qt 所有可选模块都可以这么补。我之前在无外网的工控机上补过Qt Charts和Qt Data Visualization原理完全一样模块之间大多互相独立动态库拷贝过来头文件和 CMake 配置对齐就能用。4.5 从报错反推其他可能漏选的组件串口报错只是冰山一角类似的还有报错内容漏装的组件Unknown module(s) in QT: chartsQt ChartsUnknown module(s) in QT: datavisualizationQt Data VisualizationUnknown module(s) in QT: webenginewidgetsQt WebEngineQt5Xlsx not found第三方库不是 Qt 官方模块需要单独编译安装cannot find -lQt5SerialPort链接器没找到库文件同上模块缺失所以安装时养成顺手记一下组件清单的习惯很重要。Qt 安装器在完成界面会显示已安装组件列表截图或者复制一份留档后面排查问题省一半时间。5. 装完别急着写代码:验证、维护与日常避坑组件选完、安装进度条跑满不代表万事大吉。我见过太多人安装完成就开写结果第一个 Hello World 都编译不过又回头怀疑人生。多花十分钟做验证后面能少踩很多坑。5.1 新建测试项目验证编译链路打开 Qt Creator新建一个最简单的 Widgets 应用不要勾生成 .pro之外的多余选项确认三点套件选择是正常的。编译按钮不是灰的说明编译器、调试器、Qt 版本三件套匹配正常。点击构建能正常生成可执行文件。此时 Qt Creator 底部编译输出面板会显示完整的编译命令看到g或cl调用的路径确认当前用的是你安装的编译器。运行起来界面上能弹出一个空白窗口。能弹窗说明 Qt 库加载正常动态库路径没问题。这一步能确认 80% 的安装问题。如果按钮灰掉八成是套件里 Qt 版本和编译器不匹配回到工具 → 选项 → 套件手动指定一下。5.2 检查环境变量和动态库路径Windows 下 Qt 程序运行时需要找到Qt5Core.dll等动态库。如果 Qt Creator 里能跑直接双击生成的.exe却弹出缺少 Qt5Core.dll说明环境变量PATH里没有 Qt 的bin目录。两种处理方式推荐第二种手动把C:\Qt\5.15.2\mingw81_64\bin加进系统环境变量PATH一劳永逸但机器上装多个 Qt 版本时容易路径混乱。发布程序时用 Qt 自带的windeployqt.exe工具把用到的 DLL 自动复制到程序目录# 在 Qt 的 bin 目录下执行 windeployqt.exe D:\MyProject\build\release\MyApp.exewindeployqt会扫描可执行文件的依赖把platforms、styles、imageformats等子目录和对应的 DLL 一起复制过来。这个工具是 Qt 发布程序的标配比手动拷 DLL 可靠得多。5.3 维护工具的正确使用姿势在线安装器装的 QtMaintenanceTool.exe是你的后悔药。它不仅能补装新组件还能卸载组件、更新组件、甚至删除整个 Qt 安装。有几点经验想加新模块直接添加或移除组件选好之后点更新不用卸载重装。如果只是某个组件文件损坏也可以先用维护工具重新安装该组件来修复比找安装包重装整个 Qt 强。维护工具更新组件前最好把正在跑的 Qt Creator 关掉否则可能因为文件占用导致更新失败。5.4 多版本 Qt 共存时的排序问题很多老项目可能要求 Qt 5.12新项目用 Qt 5.15 或 Qt 6这时候一台机器上会出现多个 Qt 安装实例。共存本身没问题Qt 的路径是隔离的各用各的。但要注意两点新建项目时Qt Creator 的套件选择里可能同时出现老版本和新版本的选项注意看套件名称里的 Qt 版本号别选错。.pro文件里的QT 模块在不同版本里有的名称会变比如 Qt 6 里QtSerialPort变成了SerialPort模块的一部分老项目迁移后要用维护工具补对应新版本的模块。5.5 线上环境安装的特殊经验在一个不能随便联网的环境下装 Qt最稳的办法是在一台能正常上网、系统版本和目标机器一致的电脑上装好 Qt然后把安装目录整个打包拷贝过去。打包时注意Qt 本身是绿色化的把安装目录复制到另一台机器后改一下qmake路径配置就能用。但 Qt Creator 的配置%APPDATA%\QtProject和套件信息最好也在目标机器上手动重新配置否则容易识别不到。如果目标机器也要编译 MSVC 版本需要同步确认 Visual Studio Build Tools 的安装情况。这种整目录复制的方式我帮同事解决过很多次工控机离线环境的问题比拖着几个GB的离线安装包远程传过去再一步步装要快得多。6. 最后再分享几个和组件选择相关的实用技巧组件选择这件事说大不大说小不小但它直接决定了后面写代码时会不会被奇怪的报错打断。一次性把组件选对省下来的时间足够你多看几十页文档。技巧一安装时勾选组件先想一年后。你现在只写串口工具不代表半年后不会想加个图表展示。像我一开始装 Qt 就只勾了 Desktop 和 Serial Port后来加图表需求又要重跑维护工具补Qt Charts。补装本身只要几分钟但如果你用的是离线包就得折腾半天。所以宁可安装时稍微多勾几个用得上但不确定的模块也别抠那点磁盘空间。技巧二磁盘空间分级取舍。我个人的空间分配习惯是Qt 主库 编译器工具链必须装全Sources 和 Debug Info 看剩余空间Qt WebEngine这类体积大、项目里用不到就敢直接跳过。一个最小可用的 Qt 桌面环境大约 5~8GB加 Sources 和 Charts 等常用模块也就 10~12GB比全选 30GB 低了太多。技巧三用qtchooser之类的工具管理多版本Linux/macOS 用户。Windows 上我没折腾但 Linux 下装多个 Qt 后不同项目的 qmake 版本选择很容易乱。用qtchooser -l列出已安装 Qt然后通过QT_SELECT环境变量或符号链接指定版本能减少不少 Qt 版本不对 的报错。技巧四遇到摸不准的组件先查后选。Qt 的组件列表不是固定的你永远可以在安装前把每个条目的名称扔到搜索引擎里查一下它到底是干嘛的。别凭名字猜比如Tools里的Qt Creator和Developer and Designer Tools里的Qt Design Studio名字相近但用途完全不同装错了就是好几个G的浪费。装完 Qt能弹窗、能编译、能打包这套流程跑通了后面写代码才能真正专注在业务逻辑上。组件选择只是安装的一个环节但它的影响会贯穿整个项目周期值得花点时间认真对待。希望这篇拆解能帮你在安装界面上少纠结几分钟把更多精力留给真正有意思的事情。
Qt安装组件选择全解析：从装前避坑到serialport报错补救
从来没有哪个开源框架的安装过程能让这么多人集体卡壳Qt绝对是独一份。你说它难吧下一步下一步就完事了你说它简单吧社交平台上一搜Qt安装大把人在组件选择那一步翻车。最常见的剧本就是装的时候顺手全点了硬盘爆掉或者图省事一路默认结果项目编译时甩给你一句Project ERROR: Unknown module(s) in QT: serialport当场傻眼。这篇文章不打算重复官网那份枯燥的安装向导说明我直接把组件选择界面从里到外拆开讲透每个分组是干什么的、哪些必选、哪些按需、哪些选错会埋雷以及装完之后怎么验证、怎么补救。内容基于我这些年用 Qt 5.12 / 5.14 / 5.15.2 做桌面客户端和嵌入式工具的实际经验照着勾基本不会出错。1. 为什么Qt装完老出幺蛾子:组件筛选才是安装的关键很多人的直觉是安装软件嘛能勾的全勾上功能最全肯定没错。这个思路放在普通软件上勉强成立放在 Qt 上就是灾难。一个全量勾选的 Qt 5.15.2 在线安装体积能轻松突破 30GB更离谱的是里面大量内容你根本用不上比如针对 Android、iOS、WebAssembly 的交叉编译套件。装完之后磁盘占用巨大编译的时候还要面对几十个编译套件来回切换的混乱局面。组件筛选的本质是搞清楚两件事你用 Qt 干什么以及你在什么平台上干。只写 Windows 桌面程序那你就只需要一个桌面编译套件MinGW 或 MSVC外加 Qt Creator 编辑器。要打包发布、写安装程序那可能需要 Qt Installer Framework或者额外下个 Inno Setup 之类的外部工具。要用串口、网络、数据库、图表这些功能对应的模块必须在安装时勾选否则代码里#include QtSerialPort或者QT serialport直接给你报错。要调试 Qt 源码就离不开 Sources 组件要定位 Qt 自身崩溃需要 Qt Debug Information Files。说白了组件选择的本质就是按需装配。选多了浪费磁盘和编译时间选少了后面各种unknown module报错两头都难受。这篇文章就是把需求和组件之间的对应关系捋清楚。另一个需要注意的地方是组件选择界面里经常出现一半打勾、一半空白的复选框这个叫部分选择表示该分组下有部分子项被选中。很多人看到这个灰色勾以为选上了实际漏装了一堆东西。后面我会专门说这种复选框怎么处理。2. 动手装之前,先把这三个问题想清楚在进入组件选择界面之前有三个前置问题必须确认不然选组件时你根本不知道该选哪个版本、哪个编译器。很多人上来就默认结果装完发现编译器不匹配又得重来非常浪费时间。2.1 用在线安装器还是离线安装包这是第一个岔路口。在线安装器qt-online-installer是一个体积只有几十MB的小程序运行时按需下载组件好处是灵活、可以断点续传、后续能随时用维护工具增删组件。缺点也很明显国内网络环境下下载速度很感人几十GB的依赖能挂一整晚。离线安装包则是把所有组件打包成一个巨大的安装文件单个 .run 或 .exe常见有 3GB 到 8GB 不等好处是一次下载、离线安装、可重复使用坏处是安装时不能自定义选择组件版本且后续没办法用维护工具添加新组件有的离线包可以有的不行。如果你有拷贝到内网机器上安装的需求离线包是唯一选择。从热搜词里也能看到qt离线安装包下载5.14这种具体需求说明很多人是要装内网环境或者特定版本。我的建议是个人开发、网络条件差用离线包选一个接近自己需求的版本一口气装完。团队协作、可能增减模块在线安装器 维护工具后续按需调整。2.2 编译器套件决定上限选组件前先想明白你打算用什么编译器。Qt 组件的安装列表里一个版本下面通常会有MinGW 64-bit / 32-bitGCC 的 Windows 移植版开源、随装随用不依赖 Visual Studio。MSVC 2019 / 2022 64-bit微软的 Visual C 编译器需要电脑上装对应版本的 Visual Studio 或 Build Tools。UWP做 Windows 商店应用才需要普通人碰都不用碰。Android / iOS / WebAssembly跨平台移动端和应用纯桌面开发直接跳过。这两类编译器选哪个直接决定你后面用的是mingw32-make还是nmake编译出来的依赖库也不互通。比如你用 MinGW 编译的程序想链接一个 MSVC 编译的第三方 DLL大概率出现符号冲突、链接失败。所以安装时只选一个主用编译器就够了最多加个备用别把 MinGW 和 MSVC 全装上后面切来切去容易混乱。2.3 Qt 版本不是越新越好Qt 6 已经出了好几年但不少老项目、旧依赖库还趴在 Qt 5 上这也是Qt 5.15.2 下载安装这类关键词长期霸榜的原因。Qt 5.15 是 Qt 5 系列的最后一个 LTS长期支持版本社区生态最成熟第三方库基本都能找到对应版本新学 Qt 或者维护老项目选 5.15.2 最稳。如果你是新项目、从零开始Qt 6 的 CMake 集成更现代、对高分辨率屏支持更好也是不错的选择。但注意Qt 6 的组件列表和 Qt 5 差异比较大一些模块被拆分或合并了这篇讲到的组件对照逻辑同样适用具体模块名要按你安装版本的实际情况来。这里有个经验值可以参考选版本时最好查一下它配套的 Qt Creator 和编译器版本要求三者匹配才能跑得顺。安装器通常会默认选好匹配的 Qt Creator但如果你在安装器里手动取消了后面再单独装 Creator版本和 Qt 库不匹配时会出现在套件页面里找不到编译套件或者识别不到 Qt 版本的情况。3. 组件选择界面逐项拆解:哪些必选,哪些按需,哪些别碰现在进入正题组件选择界面长什么样、每一项到底是什么意思。以 Qt 5.15.2 在线安装器为例左侧是层级列表主要有Qt、Tools、Developer and Designer Tools三大类。下面逐个拆。3.1 Qt 主分类下的核心模块展开Qt节点你能看到一堆版本条目Qt 5.15.2、Qt 6.2.x等。展开某个版本后里面还有细分的子组件。注意这些子组件不是靠嘴说选的它们是真正要下载的库文件、源码头文件和构建工具。MinGW 8.1.0 64-bit或类似的 MinGW 条目这是你实际编译链接时要用到的 Qt 库比如 Qt5Core.dll、Qt5Widgets.dll、Qt5Gui.dll。选它等于把Windows 桌面 MinGW 编译器这一套完整编译环境拉下来。一个版本下有 MinGW 和 MSVC 两种库我的建议是先确定编译器再选对应的 Qt 库别全选。MSVC 2019 64-bit同样是 Qt 库只是编译工具链换成了 MSVC。如果你用 Visual Studio 开发插件或者想用某些只提供 MSVC 版本的第三方库就选它。前提是你机器上已经装了 Visual Studio 2019或对应版本否则 CMake/qmake 都识别不到套件。UWP这是专门给 Windows 通用应用平台准备的普通桌面开发完全用不上。选上只会白白多出几个G的下载内容而且编译目标会多出不少让你困惑的选项。跳过。SourcesQt 的源代码包。平时写代码、断点调试时如果你希望按 F11 能直接进入 Qt 源码内部看实现逻辑就必须装它。否则调试时看不到 Qt 内部调用链只能看到汇编或Source not found。我的个人习惯是只要硬盘够Sources 必勾。查一个信号从发射到槽函数执行的完整链路时源码是最权威的参考资料比网上搜到的二手教程靠谱太多。Qt Debug Information Files这个组件对应 Qt 库的 PDB 调试符号文件。程序崩溃时它能帮你把堆栈信息映射到具体的 Qt 函数名而不是一串十六进制地址。用 MinGW 时不是必须的但用 MSVC 调崩溃问题有这个和没有完全是两种排查体验。磁盘空间允许就勾上。Qt Charts、Qt Data Visualization、Qt WebEngine、Qt Serial Port 等模块这些是 Qt 的功能模块扩展对应你项目的具体需求模块用途什么时候需要勾Qt Charts折线图、柱状图、饼图等图表要画数据曲线、做仪表盘界面时Qt Data Visualization3D 数据可视化三维散点、曲面图等场景Qt WebEngine内嵌 Chromium 浏览器内核在界面里显示网页、HTML 内容时Qt Serial Port串口通信库做下位机调试工具、硬件通信Qt Network网络通信默认包含在核心库中绝大多数项目都需要尽量保持Qt Multimedia音频、视频播放和采集做播放器、音视频处理Qt SQL数据库驱动SQLite、MySQL、PostgreSQL 等需要连数据库时Qt ActiveXCOM 和 ActiveX 支持需要调用 Windows 自带 COM 组件或做 Office 集成这里要特别强调Qt 的模块勾选状态直接决定后面 qmake 的.pro文件里能不能写QT serialport。如果没勾光在.pro里加这句编译时就会报出热搜词里那个经典的错误Project ERROR: Unknown module(s) in QT: serialport。我后面会专门说这个怎么补。3.2 Tools 分类下的辅助工具Tools节点平时很多人忽略里面装着编译和开发必需的外围工具。Qt CreatorQt 官方 IDE你必须装。里面还可能分Qt Creator和Qt Creator Plugin Development两个子项后者是开发 Qt Creator 插件才需要的普通用户选前者即可。MinGW / MSVC 工具链在线安装器会帮你把 MinGW 的编译器gcc.exe、g.exe、mingw32-make.exe下下来并配好路径。如果你轨道上选了Qt 5.15.2下的MinGW 8.1.0 64-bit这里通常会自动带出对应的MinGW 8.1.0条目保持默认勾选即可。注意把 Qt 库和编译器分开列很多人以为勾了 Qt 库就够编译了实际上是两回事。Qt 库是编译链接时的依赖库MinGW 是编译器本身两个缺一不可。只勾库不勾编译器装完后打开 Qt Creator 会发现套件不完整编译按钮是灰的。CMake、Ninja如果你打算用 CMake 构建系统写 Qt 6 或现代 Qt 5 项目这两个是标配。Qt 5.15 的 qmake 不需要 CMake但很多第三方库和范例都转向 CMake 了装一下不亏。磁盘空间通常也很小。3.3 Developer and Designer Tools 分类多数人用不上这个分类下是Qt 3D Studio、Qt Design Studio这类偏设计工具的东西。Qt Design Studio 是给 UI/UX 设计师用的用来做动态界面交互设计和过渡动画。普通程序员用不到也不建议装它和 Qt Creator 的定位完全不同装上只会让安装列表更乱。3.4 勾选策略的参考模板根据不同需求我整理了一份可以直接抄作业的勾选组合以 Qt 5.15.2 为例使用场景必选组件可选/建议勾选千万别碰桌面小工具串口、网络对应版本的 MinGW 或 MSVC 库、Qt Creator、编译器工具链Sources、Qt Serial Port、Qt ChartsUWP、Android、WebAssembly跨平台桌面应用各目标平台的库、CMake、NinjaSources、Qt Network、Qt WebEngine不需要冗余的编译套件嵌入式/HMI 界面对应交叉编译工具链、Qt Quick、Qt Quick ControlsQt 3D、Data Visualization别在工作机装全套桌面库数据可视化应用对应桌面库、Qt Charts、Qt Data VisualizationSourcesUWP、移动端套件4. 漏选组件的代价与补救:serialport 报错的完整排查链路组件没勾对最常见的下场就是编译报错。我写过很多串口调试工具这块的坑踩得最多。顺着热搜词里的qt unknown module in qt:serialport和unknown module(s) in qt: serialport我把完整的排查链路和补救方法讲清楚。4.1 报错是怎么来的假设你的.pro文件里有一行QT core gui serialport或者你在CMakeLists.txt里写了find_package(Qt5 REQUIRED COMPONENTS SerialPort)编译时qmake 或 CMake 会去 Qt 安装目录里找对应的模块文件。如果安装时没勾选 Qt Serial Port 模块Qt5SerialPort.dll和对应的 cmake 配置文件根本不存在于是编译器直接报Project ERROR: Unknown module(s) in QT: serialport这个报错的迷惑性在于你的代码逻辑完全没问题问题出在安装环节。没有经验的人会反复检查代码、检查.pro格式甚至重装整个 Qt浪费大量时间。4.2 确认问题根源的三步验证法碰到这个报错先别急着重装按下面三步确认第一步查看 Qt 安装目录里有没有串口模块。找到你安装的 Qt 路径比如C:\Qt\5.15.2\mingw81_64进去看lib目录下有没有cmake\Qt5SerialPort这个目录以及bin目录下有没有Qt5SerialPort.dll。没有那就是没装这个模块。第二步用 qmake 命令行查当前 Qt 支持的模块列表# 进入 Qt 的 bin 目录 cd C:\Qt\5.15.2\mingw81_64\bin # 查看 Qt 路径配置 qmake -query QT_INSTALL_PREFIXQT_INSTALL_PREFIX会告诉你当前编译套件实际使用的 Qt 根目录确认模块缺失发生在哪一个安装实例上。如果电脑上装了多个 Qt 版本这一步能帮你定位到底用的哪一份库。第三步打开 Qt Creator 的选项 → 套件检查当前套件对应的 Qt 版本路径。有时候.pro文件里没写错但 Qt Creator 自动选择的套件指向了另一个没装串口模块的 Qt 安装目录导致同样的代码换个套件就能编译。这一步很常见也最容易被忽略。4.3 补救方式一:用维护工具补装组件Qt 在线安装器装出来的环境自带一个MaintenanceTool.exe在安装目录的根目录下。运行它选择添加或移除组件然后重新进入组件选择界面找到对应版本的Qt Serial Port勾上点下一步等待下载安装即可。补装完重新打开 Qt Creator报错就会消失。这套操作也适用于其他漏装的模块比如Qt Charts、Sources原理一致。离线安装包版本的 Qt 没有维护工具遇到漏装就麻烦了要么重新下载一个更全的离线包要么从其他机器拷贝对应模块文件到安装目录。我自己遇到过用离线包装完才发现漏了 WebEngine最后是找了一台装了同款 Qt 的机器把整个 WebEngine 相关文件拷贝过来才算解决。强烈建议内网用户记一下自己装的组件清单避免来回折腾。4.4 补救方式二:没有维护工具时的手术刀式补装对于离线包或已经删掉安装器的环境补装本质上就是缺什么文件就补什么文件。以串口模块为例你需要从同版本、同编译器套件的 Qt 安装目录里拷贝lib目录下带SerialPort的.lib、.a、.prl、.dll文件include\QtSerialPort整个头文件目录lib\cmake\Qt5SerialPort整个 CMake 配置目录mkspecs\modules下的qt_lib_serialport.pri部分版本有。如果你手头有一台装了完整版 Qt 的电脑远程拷贝或者 U 盘都行。拷贝完记得清一下 CMake 缓存或者 qmake 缓存否则可能因为缓存不一致还是报错。这个方法不仅能补串口理论上 Qt 所有可选模块都可以这么补。我之前在无外网的工控机上补过Qt Charts和Qt Data Visualization原理完全一样模块之间大多互相独立动态库拷贝过来头文件和 CMake 配置对齐就能用。4.5 从报错反推其他可能漏选的组件串口报错只是冰山一角类似的还有报错内容漏装的组件Unknown module(s) in QT: chartsQt ChartsUnknown module(s) in QT: datavisualizationQt Data VisualizationUnknown module(s) in QT: webenginewidgetsQt WebEngineQt5Xlsx not found第三方库不是 Qt 官方模块需要单独编译安装cannot find -lQt5SerialPort链接器没找到库文件同上模块缺失所以安装时养成顺手记一下组件清单的习惯很重要。Qt 安装器在完成界面会显示已安装组件列表截图或者复制一份留档后面排查问题省一半时间。5. 装完别急着写代码:验证、维护与日常避坑组件选完、安装进度条跑满不代表万事大吉。我见过太多人安装完成就开写结果第一个 Hello World 都编译不过又回头怀疑人生。多花十分钟做验证后面能少踩很多坑。5.1 新建测试项目验证编译链路打开 Qt Creator新建一个最简单的 Widgets 应用不要勾生成 .pro之外的多余选项确认三点套件选择是正常的。编译按钮不是灰的说明编译器、调试器、Qt 版本三件套匹配正常。点击构建能正常生成可执行文件。此时 Qt Creator 底部编译输出面板会显示完整的编译命令看到g或cl调用的路径确认当前用的是你安装的编译器。运行起来界面上能弹出一个空白窗口。能弹窗说明 Qt 库加载正常动态库路径没问题。这一步能确认 80% 的安装问题。如果按钮灰掉八成是套件里 Qt 版本和编译器不匹配回到工具 → 选项 → 套件手动指定一下。5.2 检查环境变量和动态库路径Windows 下 Qt 程序运行时需要找到Qt5Core.dll等动态库。如果 Qt Creator 里能跑直接双击生成的.exe却弹出缺少 Qt5Core.dll说明环境变量PATH里没有 Qt 的bin目录。两种处理方式推荐第二种手动把C:\Qt\5.15.2\mingw81_64\bin加进系统环境变量PATH一劳永逸但机器上装多个 Qt 版本时容易路径混乱。发布程序时用 Qt 自带的windeployqt.exe工具把用到的 DLL 自动复制到程序目录# 在 Qt 的 bin 目录下执行 windeployqt.exe D:\MyProject\build\release\MyApp.exewindeployqt会扫描可执行文件的依赖把platforms、styles、imageformats等子目录和对应的 DLL 一起复制过来。这个工具是 Qt 发布程序的标配比手动拷 DLL 可靠得多。5.3 维护工具的正确使用姿势在线安装器装的 QtMaintenanceTool.exe是你的后悔药。它不仅能补装新组件还能卸载组件、更新组件、甚至删除整个 Qt 安装。有几点经验想加新模块直接添加或移除组件选好之后点更新不用卸载重装。如果只是某个组件文件损坏也可以先用维护工具重新安装该组件来修复比找安装包重装整个 Qt 强。维护工具更新组件前最好把正在跑的 Qt Creator 关掉否则可能因为文件占用导致更新失败。5.4 多版本 Qt 共存时的排序问题很多老项目可能要求 Qt 5.12新项目用 Qt 5.15 或 Qt 6这时候一台机器上会出现多个 Qt 安装实例。共存本身没问题Qt 的路径是隔离的各用各的。但要注意两点新建项目时Qt Creator 的套件选择里可能同时出现老版本和新版本的选项注意看套件名称里的 Qt 版本号别选错。.pro文件里的QT 模块在不同版本里有的名称会变比如 Qt 6 里QtSerialPort变成了SerialPort模块的一部分老项目迁移后要用维护工具补对应新版本的模块。5.5 线上环境安装的特殊经验在一个不能随便联网的环境下装 Qt最稳的办法是在一台能正常上网、系统版本和目标机器一致的电脑上装好 Qt然后把安装目录整个打包拷贝过去。打包时注意Qt 本身是绿色化的把安装目录复制到另一台机器后改一下qmake路径配置就能用。但 Qt Creator 的配置%APPDATA%\QtProject和套件信息最好也在目标机器上手动重新配置否则容易识别不到。如果目标机器也要编译 MSVC 版本需要同步确认 Visual Studio Build Tools 的安装情况。这种整目录复制的方式我帮同事解决过很多次工控机离线环境的问题比拖着几个GB的离线安装包远程传过去再一步步装要快得多。6. 最后再分享几个和组件选择相关的实用技巧组件选择这件事说大不大说小不小但它直接决定了后面写代码时会不会被奇怪的报错打断。一次性把组件选对省下来的时间足够你多看几十页文档。技巧一安装时勾选组件先想一年后。你现在只写串口工具不代表半年后不会想加个图表展示。像我一开始装 Qt 就只勾了 Desktop 和 Serial Port后来加图表需求又要重跑维护工具补Qt Charts。补装本身只要几分钟但如果你用的是离线包就得折腾半天。所以宁可安装时稍微多勾几个用得上但不确定的模块也别抠那点磁盘空间。技巧二磁盘空间分级取舍。我个人的空间分配习惯是Qt 主库 编译器工具链必须装全Sources 和 Debug Info 看剩余空间Qt WebEngine这类体积大、项目里用不到就敢直接跳过。一个最小可用的 Qt 桌面环境大约 5~8GB加 Sources 和 Charts 等常用模块也就 10~12GB比全选 30GB 低了太多。技巧三用qtchooser之类的工具管理多版本Linux/macOS 用户。Windows 上我没折腾但 Linux 下装多个 Qt 后不同项目的 qmake 版本选择很容易乱。用qtchooser -l列出已安装 Qt然后通过QT_SELECT环境变量或符号链接指定版本能减少不少 Qt 版本不对 的报错。技巧四遇到摸不准的组件先查后选。Qt 的组件列表不是固定的你永远可以在安装前把每个条目的名称扔到搜索引擎里查一下它到底是干嘛的。别凭名字猜比如Tools里的Qt Creator和Developer and Designer Tools里的Qt Design Studio名字相近但用途完全不同装错了就是好几个G的浪费。装完 Qt能弹窗、能编译、能打包这套流程跑通了后面写代码才能真正专注在业务逻辑上。组件选择只是安装的一个环节但它的影响会贯穿整个项目周期值得花点时间认真对待。希望这篇拆解能帮你在安装界面上少纠结几分钟把更多精力留给真正有意思的事情。
