企业官网建设流程全解析

周五下午，同事把一个 Qt 工程甩过来，说他机器上死活编不过。我打开一看，.pro里老老实实写着一行QT += webenginewidgets，Creator 代码编辑区没报红，但一按构建，输出窗口只丢下一句冷冰冰的提示：:-1: error: Unknown module(s) in QT: webenginewidgets。这个报错，几乎每个想用 Qt 做内嵌浏览器、Markdown 预览器、HTML 报表渲染、仪表盘大屏的人都会撞上一次，而且它的迷惑性在于——代码看着一点问题没有，错确实不在代码里。

Qt WebEngine 是 Qt 生态里少数几个"体积巨大、依赖复杂、装不装全看当初勾没勾"的模块。它底层封装的是 Chromium 的渲染引擎，一个模块动辄几百兆，所以官方在安装器里把它做成了可选项；Linux 发行版的仓库包又习惯把它拆成单独的-dev包；32 位的编译器套件干脆直接不支持。这三件事叠加起来，就导致了同一个.pro文件在不同机器上命运完全不同的局面。这篇文章不打算只给你一句"去装一下 WebEngine 就行了"，而是把 qmake 判断模块存在与否的机制、五类真实成因、三步定位法、各平台的具体解决方案，以及打包部署时那些"编过了却跑不起来"的坑，一次讲透。适合刚接触 Qt 的初学者，也适合被这个问题卡了一下午、想搞清楚底层逻辑的老手。

1. 报错现象与 Qt WebEngine 的来龙去脉

1.1 一行报错背后的真实含义

先把这条报错逐字拆开看。Unknown module(s) in QT:这半句是 qmake 抛出来的，注意它说的是 "unknown"，不是 "not found"，也不是 "failed to load"。这三个词看起来差不多，含义差得很远。Unknown的意思是：qmake 在它认知范围内，压根没听说过有这么个模块。这就好比你去一家超市问有没有某个牌子的牛奶，店员回你"我们店没有这个商品分类"，而不是"这个牌子今天卖完了"——问题出在"分类"层面，不出在"库存"层面。

这个区别至关重要，因为它直接决定了排查方向。如果是库存问题（文件缺失、版本不对），你补文件就行；但如果是分类问题（qmake 不知道有这个东西），那你补再多文件也没用，得先让 qmake 知道它存在。而QT += xxx这个语法糖背后，qmake 具体做了什么动作，就是下一节要说的核心机制。

另外还有一个细节：这条报错经常只在构建时出现，代码编辑器里不标红。原因是 Qt Creator 的代码模型（Clang Code Model）有自己的头文件索引路径，它可能通过其他渠道找到了QWebEngineView的头文件，于是补全正常、跳转正常，但编译器的实际调用参数是 qmake 生成的，qmake 失败了，编译自然就进行不下去。这种"编辑区正常、构建区报错"的割裂感，是很多人被绕进去的第一个陷阱。

1.2 Qt WebEngine 与 WebKit 的取舍

要理解为什么 WebEngine 这么"娇贵"，得回到它的身世。Qt 最早用的网页渲染模块叫 Qt WebKit，基于苹果开源的 WebKit 引擎。这个模块从 Qt 4.4 一直用到 Qt 5.5 左右，体积小、依赖少、和 QWidget 体系融合得好，很多人至今怀念它。但它的问题也很明显：WebKit 分支众多、更新缓慢、对现代 Web 标准支持跟不上，尤其是 HTML5 视频、复杂 CSS3 动画、WebGL 这些能力。

于是 Qt 从 5.4 开始引入 Qt WebEngine，底层换成 Chromium，5.6 正式转正并逐步取代 WebKit。代价就是——Chromium 是个庞然大物。它自带 V8 JavaScript 引擎、自带 ICU 国际化数据（就是那个几十兆的icudtl.dat）、自带一套独立的多进程架构（这就是为什么你会看到QtWebEngineProcess.exe这个独立进程）。它的构建产物按平台不同，动辄几百兆到一两个 G。

我在实际项目里做过对比：同一个内嵌网页需求，WebKit 编译出来的可执行文件加依赖不到 50M，WebEngine 轻松超过 200M。所以官方把 WebEngine 做成安装器的可选组件、把它的构建产物单独拆包，是完全合理的工程决策。只对使用者来说，这个决策带来的隐性成本就是——你的工程在别人机器上不一定能编过，而这恰恰是团队协作里最头疼的场景。

顺带提一句，如果你只是想渲染一段简单的富文本或者做 Markdown 预览，其实不一定非要上 WebEngine。QTextBrowser 支持有限的 HTML 子集，QWebEngineView 才是完整浏览器内核。选型阶段想清楚需求，能省掉后面一大堆依赖和打包的麻烦。

2. qmake 是怎么判断模块存不存在的

2.1 mkspecs/modules 目录的秘密

现在进入最关键的机制部分。当 qmake 读到.pro文件里的QT += webenginewidgets时，它做的第一件事是把模块名转成一个文件路径，去 Qt 安装目录下的mkspecs/modules/文件夹里找一个叫qt_lib_webenginewidgets.pri的文件。找到了，就把这个.pri里的内容（头文件路径、库文件路径、依赖关系）全部展开合并到最终的 Makefile 里；找不到，就抛出Unknown module(s) in QT: webenginewidgets。

这个判断逻辑简单粗暴，但它解释了一切现象。为什么单独装个头文件没用？因为没有.pri文件，qmake 不知道头文件在哪。为什么换个 qmake 就好了？因为不同 Qt 版本的mkspecs/modules/目录内容不一样。为什么在线安装器里补装一下就好了？因为补装的动作本质上就是把那一堆.pri文件和对应的.lib/.a、.dll塞进安装目录。

你可以自己动手验证这个机制。打开你的 Qt 安装路径，比如C:\Qt\5.15.2\msvc2019_64\mkspecs\modules\，用文件管理器搜一下webengine，正常情况下应该能找到至少这几个：

• qt_lib_webenginecore.pri
• qt_lib_webenginewidgets.pri
• qt_lib_webenginequick.pri
• qt_lib_webengine.pri

如果这四个里头一个都没有，那答案已经很明确了，这个 Kit 里就没有 WebEngine。如果只缺webenginewidgets，那可能是个更冷门的情况，比如安装过程被中断导致文件没写全，需要重装该组件。

同目录下你还能看到qt_lib_serialport.pri、qt_lib_charts.pri等等，这也解释了一个热词现象：Unknown module(s) in QT: serialport和Unknown module(s) in QT: webenginewidgets是同一类病，只是缺的器官不同。凡是QT +=后面跟的东西报 unknown，八九不离十都是这个.pri文件缺失的问题。

2.2 QT += 的展开顺序与依赖链

搞清楚判定机制之后，还要理解第二层：依赖链。QT += webenginewidgets并不是只引入这一个模块，它会顺着.pri文件里写的QT.webenginewidgets.depends把这些依赖一并拉进来。以 Qt 5.15 为例，webenginewidgets的依赖大致包括core、gui、network、webenginecore、webchannel、positioning、quick、widgets等。

这意味着一个很重要的事实：只要你写了webenginewidgets，Qt Quick 相关的模块也会被隐式引入。有些人的工程本来是纯 QWidget 的，只为了加一个内嵌浏览器，结果链接时突然报一堆 Qt Quick 的符号找不到，就是这个原因。不是 WebEngine 有问题，是它的依赖树本来就长这样。

还有一个容易忽略的点：.pro里QT +=的书写顺序，在有依赖关系的时候理论上不影响最终结果，因为 qmake 会做拓扑排序。但如果有人写了QT -= webenginecore这种"显式移除"的操作，就会人为制造出一堆未定义符号错误。这类操作我在真实项目里见过，通常是从别处抄配置时连减号一起抄过来了，排查起来相当费劲，因为报错信息指向的是函数未定义，完全不提模块的事。

在 Qt 6 里，这套机制有了变化但内核没变。Qt 6 把模块拆得更细，webenginewidgets依赖webenginecore，webenginecore又依赖一大堆。Qt 6 官方主推 CMake，QT +=这种 qmake 写法虽然还支持，但已经是兼容层了。所以如果你用的是 Qt 6，排查思路要从.pri文件转到 CMake 的包配置目录，这点在第 5 章会具体讲。

3. 五类真实原因逐一拆解

3.1 组件没装：最常见也最容易被忽略

排在第一位的，八成以上都是这个。在线安装器（Qt Online Installer）在选组件那一步，默认只勾了Qt 5.15.2分组下的MSVC 2019 64-bit或MinGW 64-bit，而 WebEngine 是挂在Qt分组下的一个独立条目，需要展开树形结构往下找才能看到，名字通常叫Qt WebEngine。很多人装 Qt 的时候一路下一步，压根没看见这行字。

macOS 和 Windows 上的官方安装包都是这个逻辑。判断方法就是前面说的，去mkspecs/modules/里数文件。解决办法是用安装目录下的MaintenanceTool.exe（Windows）或MaintenanceTool.app（macOS）补装，这个工具会连到官方源，把缺的组件下载补齐。补装的时候注意一点：它会把 WebEngine 装到你所有已安装的 Kit 下面，如果你有 MSVC 和 MinGW 两套 Kit，两套都会补上，占用空间会翻倍，心里有个数。

Linux 走发行版仓库的话情况不同。Ubuntu 上apt install qtbase5-dev只装了 Qt Base，qtwebengine5-dev才是 WebEngine 的开发包。很多人照着"Ubuntu 安装 Qt"的教程装完，发现样例都能跑，就以为自己装全了，结果一碰 WebEngine 就懵。Debian、Fedora、Arch 同理，包名各异，但都是拆开装的。

3.2 Kit 不被支持：64 位是硬门槛

第二类原因有点反直觉：你可能装了 WebEngine，但你当前选的 Kit 根本用不了它。关键限制在于，官方发包的 Qt WebEngine 只提供 64 位构建，而且对编译器有明确要求。32 位的 MinGW Kit 是绝对没有 WebEngine 的，哪怕你在安装器里勾了、也装成功了，那个msvc2019_32或者mingw73_32目录下的mkspecs/modules/里依然是空的。

这不是 Qt 偷懒，而是 Chromium 内核早就放弃了 32 位支持。硬要在 32 位上跑，得自己从源码编译，而 Chromium 的源码编译是个什么量级的工程，用过的人都知道——几百 G 磁盘空间、好几个小时起步的编译时间、动不动的内存溢出。我试过一次，在 16G 内存的机器上编到一半就 OOM 了，后来直接换 64 位方案，一了百了。

所以第一件该做的事，就是确认你 Creator 左下角那个 Kit 选择器里，当前选的是不是 64 位的 Kit。如果是Desktop Qt 5.15.2 MinGW 32-bit，那报这个错完全合理，换个64-bit的就行（前提是你装了）。顺便说，如果你的应用确实有 32 位需求，那 WebEngine 这条路基本可以放弃了，考虑换成 QWebEngineView 的轻量替代方案，比如直接调系统自带的浏览器控件，或者用 Qt WebKit（Qt 5.5 及以前），或者干脆用 QTextBrowser 降级处理。

3.3 qmake 指向错误：用了"别人家"的 qmake

第三类原因在命令行走构建的时候特别常见，那就是环境变量里的 qmake 不是你 Qt Creator 用的那个。举个例子，你系统里同时有 Ubuntu 仓库装的 Qt 5.15.3 和手动下载的 Qt 5.15.2，后者是主用的，但 PATH 里/usr/bin排在前面，于是你在终端敲qmake的时候，实际调用的是系统那个。这个系统 qmake 里可能没装 WebEngine（因为qtwebengine5-dev没装），于是报 unknown。

更隐蔽的是混装导致的版本冲突。热词里有一条cannot mix incompatible qt library (5.15.3) with this library (5.15.2)就是这类问题的典型表现——运行时加载了不同 minor 版本的 Qt 库，表现是程序崩溃或者行为诡异。而编译期的 unknown module，往往就是这种"多个 Qt 共存、环境变量串了"的前兆。

判断方法很简单，用绝对路径调用 qmake 看看：

# 假设你的 Qt 装在 /opt/Qt/5.15.2/gcc_64 /opt/Qt/5.15.2/gcc_64/bin/qmake -query QT_VERSION /opt/Qt/5.15.2/gcc_64/bin/qmake -query QT_INSTALL_LIBS

qmake -query会把当前这个 qmake 认为的所有路径都打出来，其中QT_INSTALL_ARCHDATA和QT_INSTALL_LIBS指向的目录，就是它将来找模块的地方。把这两个路径拿去和实际的安装目录一对，问题立刻现形。Qt Creator 里也可以看，工具 -> 选项 -> Kits -> Qt Versions，每个条目都标着 qmake 的真实路径，鼠标悬停能看到版本号。

3.4 版本与模块拆分：名字对不上号

第四类原因是版本差异导致的模块名变化。历史上有过几次改动：Qt WebEngine 刚出来那会儿，QT += webenginewidgets这个写法只在 Qt 5.6 之后才正式可用，5.4、5.5 是技术预览阶段，模块名和现在不完全一样。如果你手上的老教程是针对那个年代的，照抄过来可能就对不上。

Qt 6 时代的拆分更彻底。Qt 6 把webenginewidgets拆成了WebEngineCore、WebEngineWidgets、WebEngineQuick三个独立模块，CMake 里要分别 find。而且 Qt 6 里 QML 用的WebEngineView从webenginequick里移到了单独的包。所以假如你从 Qt 5 迁移到 Qt 6，QT += webenginewidgets可能还能凑合，但 CMake 写法肯定要改，find_package(Qt6 COMPONENTS WebEngineWidgets)这个才是正路。

还有一种是模块名拼写和大小写的问题。CMake 里模块名是驼峰式WebEngineWidgets，qmake 里是全小写webenginewidgets，这两种写法不能混。我在论坛上见过有人 CMake 里写小写，报的也是 unknown module，排查了半天，最后发现是大小写。

3.5 静态构建与交叉编译的特殊情况

最后这一类相对小众，但踩进去的人往往找不到出路。如果你是静态编译的 Qt（-static配置），那 WebEngine 基本用不了，因为 Chromium 的多进程架构和静态链接在技术上有冲突，官方明确表示静态构建不支持 WebEngine。这个限制不是配置问题，是架构层面的，绕不过去。

交叉编译也一样。热词里有个ubuntu-20.04 安装 qt 交叉编译环境，这块的实际经验是：WebEngine 的交叉编译极其痛苦，做得好的只有少数几个目标平台（比如某些 ARM64 Linux 板子），其他平台基本处于"理论上可行、实践上劝退"的状态。所以做嵌入式项目的时候，如果需求里有内嵌网页，我一般会提前跟需求方说清楚，要么放弃 WebEngine 换成轻量方案，要么换硬件平台。

4. 三步定位法：先别急着改代码

4.1 第一步：确认当前使用的 qmake

前面说过机制，现在给一套可操作的定位流程。第一步永远是问清楚"现在到底在用哪个 qmake"，因为不确认这一点，后面所有排查都是在猜。在 Qt Creator 里，点开左下角的 Kit 选择器，选中出问题的那个 Kit，然后进项目 -> Build & Run -> Build Steps，展开 qmake 那一步，看它执行的命令行。或者更直接，在Projects面板里点qmake旁边的详情，能看到完整路径。

如果你是在命令行构建，那就更直接：

which qmake qmake -v

qmake -v的输出会告诉你两件事：版本号（比如QMake version 3.1 Using Qt version 5.15.2）和它的内部安装路径前缀。把这个路径和你在 Creator 里看到的路径对一下，一致就说明环境是干净的，可以进入下一步。

注意：Windows 上如果你用了多个 Qt 版本，where qmake（注意不是which）会把 PATH 里所有叫 qmake 的都列出来，第一个才是实际执行的那个。这个命令在排查混装问题时非常好用。

4.2 第二步：检查模块文件是否存在

确认了 qmake 之后，直接去它的安装目录下找.pri文件。路径规律是{qmake所在目录}/../mkspecs/modules/qt_lib_webenginewidgets.pri。在 Windows 上大概是C:\Qt\5.15.2\msvc2019_64\mkspecs\modules\，Linux 上大概是/opt/Qt/5.15.2/gcc_64/mkspecs/modules/。

这里会有三种结果，对应三种处理方向：

第三种情况最有迷惑性，文件明明在，但 qmake 就是看不见。这种基本可以断定是 qmake 路径的问题，或者是环境变量里QMAKEFEATURES、QMAKEPATH之类的变量被人为改过，指向了别的地方。这两个变量如果指向了错误的目录，qmake 会优先去那里找模块定义，找不到就报 unknown，而不会回退到默认目录。这种情况在 CI 环境或者多人共用的构建机上比较容易出现。

4.3 第三步：用最小工程验证

前两步都过了，还拿不准的话，就建一个最小可复现工程。不要在原工程上折腾，因为你不知道原来的.pro里有没有别的干扰项（比如前面提到的QT -=操作、自定义的QMAKEFEATURES、条件编译分支等）。最小工程只需要三行：

QT += core gui webenginewidgets TARGET = wtest TEMPLATE = app

配一个空的main.cpp，直接 include<QWebEngineView>并new一个出来，看看能不能编过。这个测试的价值在于隔离变量：如果最小工程能过、原工程不能过，那问题在你原工程的.pro配置里；如果最小工程也过不了，那问题就在环境上，回去查前两步。

我在团队里推行这套三步法的经验是，它能帮大多数人省掉至少一小时的瞎试时间。因为常见的错误做法是——看到报错就上网搜，搜到一句"装一下 WebEngine"，然后就去重装，装完发现还是不行，其实问题可能根本不在装没装上。

5. 按场景落地的解决方案

5.1 Windows 和 macOS：用 MaintenanceTool 补装

Windows 和 macOS 上最省事的路径就是用官方的维护工具。Windows 下在 Qt 安装根目录找MaintenanceTool.exe，macOS 下在/Users/{用户名}/Qt或者/opt/Qt下找MaintenanceTool.app。打开之后选 "Add or remove components"，展开Qt分组，找到对应版本号下的Qt WebEngine，勾上，下一步。

这里有几个实操细节值得说。第一，MaintenanceTool需要登录你的 Qt 账号，如果当初是离线包安装的，可能会提示需要在线源，得先去官网把源配好。第二，补装过程会下载几百兆到 1G 不等的文件，网络不稳的时候容易中断，中断后重开工具它会提示"部分组件已损坏"，这时候选修复。第三，装完之后必须重启 Qt Creator，因为 Creator 启动时会缓存 Kit 信息，不重启的话它可能还是看不到新模块。

装完再去mkspecs/modules/目录看一眼，qt_lib_webenginewidgets.pri应该就出现了。这一步验证很有必要，不要装完就以为万事大吉。

5.2 Linux：走发行版仓库还是官方包

Linux 上有两条路，各有取舍。走发行版仓库，比如 Ubuntu 20.04 装qtwebengine5-dev，优点是依赖自动解决、和系统 Qt 版本严格对齐、装完就能用；缺点是版本往往比官方旧，而且如果你用了官方下载的 Qt 离线包，系统包和它是两套东西，容易混。

走官方离线包，好处是版本可控、和官方文档一致，坏处是要自己处理一堆运行时依赖，最常见的就是缺libnss3、缺各种字体库、缺 GPU 相关的库。WebEngine 启动的时候如果缺这些，表现不是启动失败，而是启动后白屏或者进程直接崩，报错信息还特别含糊。

# Ubuntu 20.04 下的常见依赖，缺哪个补哪个 sudo apt-get install -y libnss3 libxss1 libasound2 libxtst6 \ libfontconfig1 libfreetype6 libx11-xcb1 libxcb-icccm4 \ libxcb-image0 libxcb-keysyms1 libxcb-randr0 libxcb-render-util0 \ libxcb-shape0 libxcb-xinerama0 libxcb-xkb1 libxkbcommon-x11-0

我个人在项目里的做法是，如果团队规模不大、不需要跨很多 Qt 版本，就直接用仓库包，省心。如果项目要用 Qt 5.15.2 这种特定版本做长期维护，那就用官方离线包，但一定要把依赖清单整理成脚本，写进 CI 里。

5.3 换 Kit 与编译器的取舍

如果你的 Kit 是 32 位的，那前面说了，唯一正路就是换 64 位。换的时候注意，32 位和 64 位工程有时候会有细微差异，比如某些 Windows API 的调用约定、指针大小相关的代码，所以换 Kit 之后不要只看编译过不过，还要跑一遍测试用例。

如果是从 MinGW 换到 MSVC，除了 Kit 本身，还要注意工程里的第三方库是不是兼容。MinGW 编译的静态库不能直接给 MSVC 用，这个是 ABI 层面的不兼容，报错通常是链接期的符号找不到，长得和模块缺失有点像，但错误信息里会有unresolved external symbol。别把这两种搞混了。

还有一个方案是放弃官方预编译包，自己从源码编译 Qt WebEngine。我一般不建议走这条路，除非你确实有定制需求（比如裁掉某些功能减小体积、或者目标平台官方不发包）。自己编的过程大概是这样：装 Python、装 Ninja、装一堆系统库，然后configure的时候加-webengine参数，最后编译。整个过程顺利的话半天到一天，不顺利的话几天都出不来。所以除非万不得已，还是换 Kit 更划算。

5.4 CMake 工程在 Qt 6 下的正确写法

Qt 6 项目现在绝大多数是 CMake 构建，写法要换。核心是三行：

find_package(Qt6 REQUIRED COMPONENTS Core Gui Widgets WebEngineWidgets) target_link_libraries(myapp PRIVATE Qt6::Core Qt6::Gui Qt6::Widgets Qt6::WebEngineWidgets)

注意WebEngineWidgets的驼峰大小写，以及Qt6::前缀。如果你是从 Qt 5 迁移过来的，原来的QT += webenginewidgets部分要全部删掉换成这一套。

排查 CMake 版本的时候，find_package失败会有更明确的报错，通常会告诉你它去哪几个路径下找过了、都没找到。这个信息比 qmake 的Unknown module友好得多，把那些路径记下来，对着看缺哪个文件，就知道该装什么了。

# 想知道 CMake 到底在哪找包，加上这个参数看详细日志 cmake -S . -B build --debug-find-pkg=Qt6WebEngineWidgets

这个--debug-find-pkg参数是我在排查一个 CI 上偶发的模块找不到问题时发现的，非常有用，它会打印出 CMake 搜索的每一个目录和每一个候选文件名。

5.5 依赖补全与工程模板

前面提过，webenginewidgets会拖进来一串依赖。在 qmake 工程里最稳妥的写法是显式写全：

QT += core gui widgets network QT += webenginecore webenginewidgets CONFIG += c++17

虽然 qmake 会自动补全依赖，但显式写出来有两个好处：一是别人接手这个工程时一眼能看明白需要什么；二是将来如果 Qt 版本升级改了依赖关系，你显式写的这部分不受影响。我在团队里维护的工程模板就是按这个思路来的，把常用模块分类列清楚，谁要加就往上加，不允许写QT += webenginewidgets一句了事。

对于 Qt 6 的 CMake 工程，推荐把这些模块统一在一处 find，避免散落在各个子目录里，将来升级版本时漏改。

6. 打包部署：能编过不等于能跑起来

6.1 Windows 下必须带的文件清单

这是另一个高频翻车点。很多人编译过了，本地跑得好好的，打包发给别人一运行就闪退，或者干脆白屏。原因就是 WebEngine 依赖一堆运行时资源，而普通的打包脚本（比如简单的windeployqt）可能会漏掉一些。

Windows 下必须一起带的至少有这些东西：

windeployqt在较新版本里会自动处理这些，但前提是它对 WebEngine 的支持版本要对上。我的习惯是打包完在一台干净的虚拟机里实测一遍，不要相信"本机能跑就行"。虚拟机上没有开发环境，能跑起来才是真的能跑起来。

6.2 Linux 与 macOS 的打包注意事项

Linux 下打包一般用 AppImage 或自研的目录结构。WebEngine 在这里的坑主要是qtwebengine_locales和resources这两个目录的路径问题——程序在运行时会按相对路径或环境变量去找它们，路径不对就渲染不出东西。可以用QTWEBENGINE_RESOURCES_PATH和QTWEBENGINE_LOCALES_PATH这两个环境变量显式指定，在启动脚本里设上最保险。

macOS 则是要把 WebEngine 的辅助 app bundle 一起塞进主 bundle 的Frameworks目录下，并且修正它们的 rpath。这一步如果用macdeployqt一般会自动处理，但自定义构建或者混合打包的时候，很容易漏。表现是主程序能启动，但内嵌页面永远是空白。

还有一点，Windows 上的QtWebEngineProcess.exe在某些杀毒软件里会被误报，这个只能靠加白名单或者给用户发说明解决，技术上绕不过去。

7. 连带问题与排查速查

7.1 serialport 等其他模块的同类报错

前面说过，Unknown module(s) in QT: serialport和本文讨论的问题同源。差别在于，SerialPort 模块体积小，很多情况下你只需要补一个小包就行。Linux 上apt install libqt5serialport5-dev，Windows 上用 MaintenanceTool 补Qt Serial Port，macOS 同理。因为它小，有时候甚至可以自己在工程里放一份串口操作的封装代码，绕开这个模块。

其他常见的同类报错还有charts、multimedia、svg、sql等等。规律是一样的：去mkspecs/modules/里找对应的.pri文件，没有就补装。我把这个规律总结成一句话给团队新人：Qt 报 unknown module，先在安装目录里找 .pri 文件，找不到就是没装，找到了就是 qmake 不对。

7.2 常见问题速查表

把整个排查过程中可能遇到的问题整理成一张表，方便对照：

7.3 我踩过的坑与经验

最后聊几个别人文档里不太会写、但我自己真切踩过的点。

第一个是关于"离线安装包"。很多人图省事下载离线安装包，结果发现离线包里根本没有 WebEngine 这个选项。这是因为离线包为了控制体积，默认不含 WebEngine 这种超大组件。要装 WebEngine 得用在线安装器，或者单独下载对应的组件包。热词里那个qt离线安装包下载5.14的需求，如果要用 WebEngine，光靠离线包是解决不了的。

第二个是包管理器和手动安装混用的问题。有一回在一台机器上排查，qmake 正常、.pri文件也在，就是编译报错。最后发现是这台机器上同时存在通过仓库装的 Qt 和手动解压的 Qt，PKG_CONFIG_PATH指向了系统那套，导致间接依赖的库版本对不上。这种混装环境是所有疑难杂症的温床，能统一就统一。

第三个是 Creator 的缓存问题。有几次补装完组件、也重启了，.pri文件确实在，但 Creator 的 Kit 页签里还是不显示 WebEngine。这时候可以试着删掉 Creator 的用户配置目录（Windows 上在%APPDATA%\QtProject，Linux 上在~/.config/QtProject），让它重新扫描一遍。删之前记得备份，因为你自定义的快捷键、配色什么的都在里面。这个办法比较暴力，但对缓存类问题通常非常有效。

第四个经验是关于排查顺序的。遇到这个报错，先看 Kit 是不是 64 位，再看 .pri 文件在不在，最后看 qmake 路径。这个顺序不是拍脑袋定的，而是按发生概率排的。前面这几百字里出现过的所有情况，九成都能用这三步定位出来，剩下的那一成才是真正需要深挖的环境问题。养成这个顺序，能省掉大量时间。

至于 WebEngine 本身在项目里的使用，如果你只是想显示一个静态 HTML，其实QTextBrowser就够了；如果你要跑 JavaScript、要渲染现代网页，那 WebEngine 是必需，但记住它的体积和打包复杂度，在项目方案评审阶段就把这部分成本算进去，别等到快要发版了才发现打包出来 300M。