企业官网建设流程全解析

如果你正在搜索引擎里翻“QT下载安装教程”，八成是已经受够了官网那套先注册、再登录、然后点半天才能下载的流程。这篇博文就只讲一件事：怎么用最快、最省事的方式把 Qt 装好，全程不注册、不登录、不看脸色，国内镜像站直接拿离线安装包，跟着点完下一步就能开始写 UI。文章会覆盖版本怎么选、镜像在哪找、安装时哪些组件必须勾、装完怎么验证环境，以及我这些年踩过的几个常见坑。适合刚接触 Qt 的新手，也适合想在内网快速部署 Qt 环境的同学直接抄作业。

1. 装之前先想清楚：你要装的到底是哪个 Qt

1.1 为什么很多人还在搜 Qt 5.14 离线包

闲聊一个现象：我在技术社区里看到“qt离线安装包下载5.14”一直是高搜索词。不是因为 5.14 有多新，恰恰是因为它足够经典。Qt 5.14.2 是官方最后一批向开源用户完整提供离线安装包的版本之一，安装包拿到手就能装，不需要在线下载器，不需要 Qt 账户。而到了 5.15 LTS 和 Qt 6 时代，官方策略收紧，开源用户下载离线包越来越麻烦，在线安装器又强制要求登录账号，于是大家翻来翻去还是回到 5.14.2。很多公司内部的旧项目、外包项目、工厂里的工业软件，至今跑的还是 Qt 5.14 甚至更早的 5.12，从兼容性角度讲，5.14.2 也足够在 Windows 上干活了。

那是不是完全不建议 Qt 6？不是。Qt 6 的改动不小，QML 模块拆分、要求 C++17、Widgets 类别的 API 虽然还在但重心已经明显偏向 QML，新手一上来直接学 Qt 6 也不是不行。问题在于，如果你只是想要一个“装完就能用、教程也最好找”的环境，5.14.2 依然是最不容易出意外的选择。等把这套流程吃透了，以后再装 Qt 6 也顺理成章，毕竟安装器的操作逻辑是类似的。

1.2 在线安装器和离线安装包到底差在哪

很多人被 Qt 官方那个在线安装器折磨过。那个叫 qt-unified-windows-x64-online.exe 的玩意儿，下载速度慢，过程中要先创建 Qt 账户、登录、选择一个开源协议页面，然后才开始真正拉取组件。要是公司网络再有点限制，基本上就是无限转圈。

离线安装包就不一样，它把整个 Qt 环境和组件全部打进一个.exe文件里，双击以后就是传统的向导式安装，老版本安装器连登录步骤都没有。对初学者来说，这是最友好的形态：不需要理解什么仓库、源、更新通道，纯傻瓜式一路 Next。对网络条件不好的环境来说，离线包也避免了下到一半断线、重来的情况。所以我的结论很直接：自己学习或内网部署，优先选离线安装包；只有当你确实需要 Qt 6 最新特性、又无法从镜像站拿到离线包时，才去用在线安装器。

2. 免登录下载的三个可靠渠道

2.1 国内镜像站：最快也最省心

要免登录下载 Qt，最靠谱的办法就是国内开源镜像站。这里说的“镜像”不是别的，就是各大高校和云服务商把 Qt 官方的历史安装包备份了一份，放在自己的服务器上供人下载。因为是国内的线路，速度通常能达到几 MB 每秒，比访问国外服务器舒服太多。

我常用的有三个，按优先级排：

这三个镜像站的内容都是从 Qt 官方同步过来的，通常用于下载历史版本，不涉及任何注册或登录环节。注意不要在搜索引擎里点进一些高仿官网的站点，有些第三方站点下载速度慢是小事，安装包里被塞进推广软件才让人头疼。镜像站的域名后缀是 .edu.cn 或 aliyun.com，特征比较明显，认准了再下载。

2.2 安装包文件名怎么读

打开镜像站以后，很多人会被一堆目录绕晕，我今天把路径拆开讲一下。以清华镜像为例，进入 mirrors.tuna.tsinghua.edu.cn/qt 之后，你会看到 archive、online_installers、development_releases 这样的目录。我们只关心 archive，它存的是历史发布版本，点进去再按 qt/5.14/5.14.2 的顺序找，最终你会看到一堆安装包文件。

Windows 下的离线安装包命名是 qt-opensource-windows-x86-5.14.2.exe。这个名字拆开看就是：Qt 开源版、Windows 平台、x86 架构（实际能跑在 64 位系统上）、版本号 5.14.2。整个文件大概 2GB 左右，所以下载前先确认磁盘空间够用。如果看到的是 qt-opensource-linux-x64-5.14.2.run，那是 Linux 的安装包；macOS 对应的是 .dmg 文件。别下错平台。

关于镜像站的选择，我还想多说一句：如果你在北京，清华镜像通常是最快的；如果你在南方或者网络环境偏电信联通，中科大和阿里云实测下来也都很稳。实在不确定的话，三个镜像都 ping 一下，哪个延迟低用哪个。下载的时候建议用浏览器单线程直接下，如果浏览器老断，可以试试迅雷之类的下载工具，但下载完最好比对一下哈希值（后文会讲），防止文件损坏。

2.3 下载之后先做一件事：校验文件

这件事很多人会跳过，但我强烈建议你不要省。2GB 的文件，下载过程中网络稍微抖动一下，可能就损坏了。损坏的安装包双击以后往往弹出奇怪的报错，或者装到一半才失败，白白浪费时间。镜像站一般会在同目录下提供 .md5 或 .sha256 校验文件，下载后算一下本地哈希值，和官网给的比对一下，一致再安装。

Windows 上校验文件我一般不用第三方小工具，PowerShell 里一行命令就够了：

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

把输出的哈希值和镜像站上提供的 SHA256 进行比对，一致就说明文件完好，开始安装。实际用下来，5.14.2 这个安装包比较稳定，我从几个镜像站下载过，还没有碰到过坏包的情况，但校验这个好习惯值得保留，尤其是以后装别的软件时也通用。

3. 安装全流程：从双击到命令行能编译

3.1 安装向导逐页操作

拿到安装包以后，双击运行。老版本的 Qt 安装器界面比较朴素，从欢迎页到安装路径页，基本就是一套标准的 Windows 向导。唯一要注意的就是安装路径，我强烈建议你直接用默认的 C:\Qt，不要改成中文路径，也不要带空格。我自己见过太多人把 Qt 装到 E:\软件工具\Qt 这种目录下，后面编译时遇到各种莫名其妙的路径编码错误，排查半天才发现是安装路径惹的祸。

安装器会问你选择安装哪些组件，这一步非常重要，下一节详细讲。组件选完以后，安装器会显示最终的系统盘空间占用（装了东西之后一般要预留 10GB 以上），确认没问题点击“安装”开始解压。整个解压安装过程大概需要 5 到 15 分钟，取决于硬盘速度。老版本安装器全程不需要登录 Qt 账户，装完了也不需要激活，这是它最讨喜的地方。

3.2 组件勾选：漏了编译器你就白装了

组件选择是整个安装过程中最关键的步骤，也是新手最容易出错的地方。Qt 安装器里的组件列表是树状结构，上面是 Qt 5.14.2 这个大节点，下面是各种模块；再往下还有一个 Tools 节点，里面放的是编译器和 IDE。我的建议是，第一次安装时重点勾这几项：

这个表值得你截图保存。尤其是 MinGW 编译器，我见过很多新手在组件页面一路 Next，最后打开 Qt Creator 发现构建套件（Kit）里是空的，查了半天才发现压根没装编译器。另外 Qt 5.14.2 的组件列表里，很多模块默认并不是全选状态，比如 Qt SerialPort 这个模块就是藏在 Qt 5.14.2 节点下，需要展开勾选，后面编译报 unknown module 的坑就是这么来的。

3.3 MinGW 和 MSVC 怎么选

Windows 上做 Qt 开发，编译器主要就两条路：MinGW 和 MSVC。MinGW 是一套 GCC 的 Windows 移植版，特点是你不需要装 Visual Studio，Qt 安装包自带的 MinGW 7.3.0 就够用，对新手非常友好。MSVC 是微软的编译器，需要你系统里先安装对应版本的 Visual Studio（比如 VS2017 或 VS2019），它的优点是和 Windows 生态结合更好，很多第三方 C++ 库默认是 MSVC 编译的，而且调试体验更强。

到底选哪个？我的建议很明确：如果你不是必须要用某些只有 MSVC 版本的库，优先选 MinGW。原因有三，一是省心，不用额外装 Visual Studio 那十几个 GB；二是路径简单，Qt Creator 能自动识别 MinGW 工具链，很少要手动配置；三是对于入门学信号槽、做界面来说，MinGW 和 MSVC 的性能差距根本感觉不到。你要是装了 Visual Studio，在组件列表里把 MSVC 2017 64-bit 也勾上，两者并不冲突，Qt Creator 里可以切换套件来编译。不过刚入门我不建议同时搞两套工具链，问题排查的方向会变多，容易越搞越乱。

3.4 配置 PATH 环境变量

安装完成以后还不能马上完事，建议把 Qt 的 bin 目录加到系统 PATH 里。有些教程会跳过这一步，因为 Qt Creator 内部编译时自己会找到编译器路径，不需要 PATH。但你要是想在命令行里直接跑 qmake、windeployqt 这些工具，或者用别的编辑器写 Qt 代码时在终端编译，没有 PATH 就会一路报“不是内部或外部命令”。

具体做法是：右键“此电脑” → 属性 → 高级系统设置 → 环境变量，在系统变量里找到 Path，点击编辑，把下面两个路径加进去（以默认安装路径 C:\Qt 为例）：

C:\Qt\5.14.2\mingw73_64\bin C:\Qt\Tools\mingw730_64\bin

第一个路径里有 qmake.exe，第二个路径里有 g++.exe。加完以后，重新打开一个 CMD 窗口，分别输入 qmake -v 和 g++ --version，只要能正常输出版本号，就说明环境配好了。这一步做完，你从图形界面到命令行，工具链都算是通的状态，后续不管你用什么编辑器写 Qt 代码，底层都是这套编译工具在干活。

4. 建第一个工程：装好没装好，跑一个就知道

4.1 Qt Creator 图形界面验证

环境配完，我习惯先新建一个最简单的 Widgets Application 来验证整套链路。打开 Qt Creator，点“新建项目”，左侧选 Application，中间选 Qt Widgets Application，然后按向导走。项目名称可以叫 helloworld，注意路径不要放进带中文的目录。创建向导会让你选择构建套件，这里应该能看到一个名字类似 “Desktop Qt 5.14.2 MinGW 64-bit” 的套装，如果能看到，说明上一节的 MinGW 被正确识别了，勾上它继续。

接下来向导会生成一个带 .pro 文件、main.cpp 和 mainwindow.cpp 的工程，你不需要写任何代码，直接点左下角的绿色三角按钮构建并运行。如果一切正常，屏幕上会弹出一个空的窗口，标题是 MainWindow。这个窗口弹出来的那一刻，你的 Qt 开发环境就正式算装好了。我第一次装 Qt 的时候是在一台老笔记本上，构建花了差不多一分钟，窗口弹出来的时候那种成就感，现在想想还挺有意思的。

4.2 纯命令行编译一个 Widgets 程序

Qt Creator 跑通之后，我还建议你用命令行再走一遍编译流程。这不只是“多此一举”，它能帮你验证 PATH 环境变量是否真的生效，也让你理解 Qt 工程的编译到底发生了什么。新建一个文件夹，比如 hello，在里面放一个 main.cpp：

#include <QApplication> #include <QLabel> int main(int argc, char *argv[]) { QApplication app(argc, argv); QLabel label("Hello, Qt"); label.resize(200, 100); label.show(); return app.exec(); }

写完后，在命令行里 cd 到这个目录，依次执行：

qmake -project qmake mingw32-make

第一条命令生成.pro工程文件，第二条命令根据.pro生成Makefile，第三条命令调用编译器生成可执行文件。如果这一步没有报错，你会看到目录下多了一个 hello.exe，直接在命令行运行，就能弹出那个显示“Hello, Qt”的小窗口。

这整套编译链路能跑通，说明 Qt 库、MinGW 编译器、环境变量三者已经完全对齐。以后就算哪天 Qt Creator 抽风了，你也有一条备用编译路径，不至于卡死在工具上。

5. 常见报错与避坑实录

5.1 编译时报 unknown module(s) in Qt: serialport

这个问题在 Qt 用户群里出现频率极高。现象是你写了一个用了串口的工程，在 .pro 文件里写了QT += serialport，一编译就报Project ERROR: Unknown module(s) in QT: serialport。我在热搜词里看到这个查询量很大，这里重点说一下。

根因很简单：安装 Qt 时没有勾选 Qt SerialPort 模块。解决分两步。第一步，打开 Qt 安装目录下的 MaintenanceTool.exe（就是安装器自带的维护工具），选择“添加或移除组件”，在 Qt 5.14.2 节点下找到 Qt SerialPort，勾上之后更新。这个过程不需要 Qt 账户登录，因为它读取的是你本地安装信息。第二步，更新完组件后，一定不要忘了重新编译工程，最好先执行一次 qmake 再构建，因为 Makefile 需要重新生成才能识别新加的模块。我在公司帮同事排查这个问题时，发现大部分人连第二步都忘了，组件装完之后不重新 qmake，照样报错。

另外还有一种情况，你确实勾选了 SerialPort，但它出现在别的套件下。比如你装的是 MSVC 套件，却在 MinGW 套件里写QT += serialport，也会找不到模块。这种时候就到项目构建套件设置里，确认当前套件对应的 Qt 版本确实包含你要的模块。

5.2 Kit 里没有编译器

装完 Qt 打开 Qt Creator，会发现左侧套件选择器是空的，或者提示“No suitable kits found”，构建时找不到编译器。这是我见过最普遍的第二个问题。原因就一个：安装时漏勾了 Tools 节点下的 MinGW 编译器，或者组件列表里的 MinGW 和 Qt Creator 版本对不上。

解决方法是重新运行 MaintenanceTool.exe，选择“添加或移除组件”，把 Tools 下的 MinGW 7.3.0 和 CMake 一并装上。装完以后回到 Qt Creator，点击菜单栏“工具” → “选项” → “Kits”，一般会自动检测到新的编译器。如果没检测到，就在“编译器”标签页手动添加，编译器路径指向 C:\Qt\Tools\mingw730_64\bin\g++.exe，qmake 路径指向 C:\Qt\5.14.2\mingw73_64\bin\qmake.exe，然后给套件手动指定这两个路径。这个方法是我摸索出来的，之前有同事手动装了一个别的 MinGW 版本，Qt 识别不出来，最后就是在 Kits 页面里手填路径解决的。

5.3 程序跑起来提示找不到 Qt5Core.dll

在 Qt Creator 里点绿色三角运行，一切正常。但你跑到 exe 所在目录，双击那个 exe，却弹窗提示“找不到 Qt5Core.dll”或“无法定位程序输入点”。这个问题也很经典，原因是 Qt Creator 运行时会把 Qt 的 bin 目录临时加进 PATH，所以它能找到 DLL；但脱离了 Qt Creator，系统就找不到 Qt 的运行时库了。

解决方案比较简单粗暴，在发布程序时，把依赖的 Qt DLL 复制到 exe 同目录，或者直接用官方提供的 windeployqt 工具自动部署。在命令行执行：

windeployqt helloworld.exe

它会把程序依赖的 Qt DLL、插件、翻译文件等一股脑复制到 exe 所在目录，这也是后期做软件发布时几乎必用的一步。如果你只是临时测试，也可以把 C:\Qt\5.14.2\mingw73_64\bin 加进系统的 PATH，但这个方法不推荐用在实际项目发布中，毕竟你不能要求每台目标机器都装一遍 Qt。

5.4 路径里有中文、空格导致的怪问题

最后说一个特别魔幻的坑。之前有个同学把工程放在 D:\课程设计\第一次实验\ 下面，每次编译都在最后链接阶段报错，错误信息还不是固定的，一会儿是找不到文件，一会儿是文件格式不对。折腾了很久，最后把工程挪到 D:\QtProjects\test 下，一次编译就过了。原因就是 Qt 的构建系统对中文路径和空格的支持不够友好，源文件路径里一旦混入中文或空格，很容易触发工具链的路径解析问题。常见表现五花八门，排查起来极费时间。

所以这个避坑点虽然说起来很简单，可真遇到时很少有人能第一时间想到。安装目录、工程路径、源码文件路径，这三处尽量都用纯英文，最稳妥。另外，公司里如果是多人协作，建议统一一下 Qt 版本和编译套件，不然你拿 Qt 5.14 打开别人 Qt 5.12 建的工程，或者反过来，总会有一些奇奇怪怪的兼容问题冒出来。

我个人的一个小习惯是：把常用的 Qt 离线安装包存在网盘里一份，给别人推荐 Qt 的时候也直接发镜像站路径和文件名，不再重复解释怎么注册账号。装环境这件事本身不复杂，大部分时间都耗在版本不匹配和组件漏勾上。希望这篇文章能让你少走这些弯路，一次装完，直接开始写代码。