简介：面向需要搭建 Qt 开发环境、却受限于 5.15.0 在线安装器的开发者与运维人员，这份 PDF 围绕官方源下载缓慢、安装程序崩溃、镜像下载数据量过大等常见阻塞点，整理了一套可复用的排错与落地思路。压缩包内仅含 1 个 PDF 文件，体积约 833KB，篇幅精炼，便于随取随查。内容结合 Fiddler 代理规则、国内镜像站点切换与组件分批安装等场景，重点呈现问题定位依据、配置示例和失败后的调整方向，帮助读者理解在线安装链路中网络与数据量之间的取舍。已有 12109 人学习下载，说明其在 Qt 环境部署场景中具备较高参考价值，适合希望减少反复试错、快速恢复安装流程的中高级开发者对照使用。

1. 装 QT 5.15.0 在线安装，我卡在 29% 的那四个晚上

装 QT 5.15.0 这件事，我在四台机器上折腾过。头一回在线安装跑到 29% 就停住，进度条灰了，任务管理器里安装器的内存一路涨到两个多 G，然后窗口自己没了。A 同学重试到第五次直接放弃，翻出 5.12 的旧离线包顶上，结果工程里的 C++17 特性报错一片，Kit 配了一下午没配起来。QT 5.15.0 之后官方只提供在线安装器，安装器本身没问题，问题出在它一次性要拉的归档文件太多、源又远，中途任何一次请求超时或者内存被吃满都会前功尽弃。这篇是我最后跑通的那套 QT 5.15.0 在线安装方案，核心就两件事：用 Fiddler 4 把下载请求改写到国内镜像，再靠安装器自己的「更改」入口把组件少量多次喂进去。适合正卡在 29% 的人。

2. 版本与前置条件：Qt 5.15.0 在线安装器配 Fiddler 4 才走得通

这套环境说白了就两个主角：一个几兆的在线安装器，一个负责改请求的 Fiddler 4。前者决定你能装到哪些组件，后者决定这些组件能不能拉下来。很多人一上来就下安装器、双击、勾满组件、点下一步，然后看着进度条爬到 29% 再掉回去，重试三次以后开始怀疑是网络问题——其实不是网络断，是一次性要的量太大，中间任何一个环节撑不住就整体回滚。把版本和前置条件先摆清楚，后面每一章的参数才有地方落。

2.1 Qt 5.15.0 为什么只剩在线安装器

Qt 的发行策略在 5.15 前后改过一次，社区版不再给完整的离线安装包。你从官网能下到的就是qt-unified-windows-x86-3.2.3-online.exe这个几兆的壳子，真正的库文件和工具链，是它运行时按你勾选的组件从download.qt.io拉下来的。这个设计对官方来说省了带宽，对普通开发者来说就是把一次下载拆成了几百次小请求，任何一个失败都可能让整个流程重来。

具体的过程是这样的：安装器启动后先拉一份元数据，就是qtsdkrepository目录下的Updates.xml和一堆描述文件，用来渲染出组件勾选界面；你勾完点下一步，它再按组件把对应的归档包一个一个下下来、解压、写注册表。库文件动辄几百兆，Debug Symbols 和 WebEngine 更大。这么长的链路里，安装器的断点续传并不可靠，失败以后经常是从头再来，这就是为什么很多人卡在同一个百分比反复失败。

那能不能绕开在线安装器、直接找离线包？5.15.0 这一代基本没有官方完整离线包，网上流传的那些要么是更早版本重新打包的，要么是第三方整合的。我试过一次第三方整合包，装完qmake -v出来的版本号和目录名对不上，Qt Creator 里新建 Kit 死活识别不到编译器，排查成本比重新装一遍还高。所以这篇还是走在线安装器，只是把它的下载环节接管掉，让每次请求都落到能跑满带宽的镜像上。

还有一点要提前说明：在线安装器是有版本号的，3.2.3是这一代比较常见的一个。安装器版本和 Qt 库版本不是一回事，同一个安装器可以装 5.12、5.15，也可以装后面更新的版本。下载安装器的时候认准文件名的online字样，不要下成维护工具的包。

2.2 Fiddler 4 的选择与安装位置

Fiddler 4 是 Windows 上用了很多年的抓包工具，能拦 HTTP/HTTPS 请求，也能在请求真正发出去之前改掉它的 Host 头和路径。选它来做这件事，是因为 Qt 安装器的下载请求走的是明文 HTTP，改起来不需要处理证书那一层，规则写几行就能生效。

版本上，Fiddler 4 那一系（4.6.x）就够用，后来改名的 Fiddler Classic 也兼容，CustomRules.js的写法和 API 基本一致。运行环境要求 .NET Framework 4.6 以上，Windows 7 SP1 之后的系统要么自带，要么联网补一下就行。安装过程一路 next，没什么需要特别设置的。

装完之后有两件事要确认。第一是规则脚本的位置，它不在安装目录里，而在用户文档目录下：

%USERPROFILE%\Documents\Fiddler2\Scripts\CustomRules.js

这个路径是后面所有改动的落脚点。注意Fiddler2这个目录名是历史遗留，装的是 Fiddler 4，目录名还是 Fiddler2，别以为装错了。第二是启动后的界面，左边是会话列表，右边是详情，顶部菜单栏有 File、Edit、Rules、Tools、View、Help。规则入口在 Rules 菜单下。

关于证书：这篇的场景里 Qt 的下载请求是 HTTP，不需要处理 HTTPS 解密，Fiddler 首次启动弹的证书安装提示可以跳过。但如果你的安装器走的是 HTTPS，就必须让 Fiddler 的根证书进系统信任区，否则握手阶段就会失败，表现出来是安装器提示无法连接服务器，而 Fiddler 里连一条会话都看不到。

2.3 装之前的系统条件检查

三件事，做在装之前比装到一半再补省太多时间。

磁盘余量。Qt 5.15.0 一个编译套件加工具链，装完轻松几个 G；要是把 Qt WebEngine、Debug Information Files 也勾上，再加上安装过程中安装器自己的临时缓存，目标盘至少留 20 G 余量。我一般直接把安装目录定到空间大的盘，比如D:\Qt，路径不要带空格和中文，后面配环境变量、写.pro文件都能少踩一类莫名其妙的坑。

权限。安装器要往注册表写卸载信息，默认安装位置也在C:\Qt这种受保护目录下，所以右键「以管理员身份运行」是必须的。用普通权限跑，经常是组件下载完了、解压到一半提示写入失败，前面的下载全白费。

系统代理状态。Fiddler 启动后默认会把自己设成系统代理，退出的时候不一定能恢复干净。装完记得回头看一眼「Internet 选项 → 连接 → 局域网设置」，确认没留下一条指向127.0.0.1的配置。我遇到过装完 Qt 之后浏览器打不开网页，第一反应是 Qt 把网络搞坏了，查了半天才发现是 Fiddler 退出时没清干净。

另外一个容易被忽略的点是网卡。如果机器上有多块网卡、或者装着虚拟网卡，Fiddler 有时候会绑到错误的那一块上，表现出来就是规则写对了但请求没被拦到。稳妥的做法是装之前先把虚拟网卡禁用掉，装完再启用。

3. 改写请求：Fiddler 4 的 OnBeforeRequest 规则怎么写

环境备齐了，接下来是这套方案里唯一需要写代码的地方。原理不复杂：Qt 安装器每次请求下载文件，都会带上一个 Host 头（download.qt.io）和一个路径（/online/qtsdkrepository/...）。Fiddler 在请求发出前有个钩子，能让你把这两个值改掉，改完之后请求实际就打到镜像站去了，镜像站返回的文件内容是一样的，安装器完全感知不到。

3.1 打开 CustomRules.js 并定位 OnBeforeRequest

在 Fiddler 里按Ctrl+R，或者走菜单 Rules → Customize Rules，会弹出脚本编辑器。这个编辑器打开的就是前面那个CustomRules.js，整个文件是 JScript 语法，里面预置了一堆示例函数，大部分用不上，但别删。

要找的是这个：

static function OnBeforeRequest(oSession: Session) { // 这里就是请求发出前的钩子，所有改写逻辑写在这个函数体里 ... }

OnBeforeRequest是 Fiddler 在请求真正发出去之前调用的一次回调，参数oSession就是当前这条请求，你能读它的 Host、路径、头信息，也能直接改。同文件里还有OnBeforeResponse，那是响应回来之后的钩子，做不了重定向，别写错地方。这个坑我踩过，规则写进了OnBeforeResponse，日志一条没有，排查了半小时才发现函数名不对。

打开脚本以后先别急着改，往下翻一翻，找到OnBeforeRequest里原有的一小段示例代码，通常是注释掉的，位置大概在文件中部靠后。把你要写的规则放在这个函数体的最前面，别放在if分支里面，避免被原有逻辑挡住。

3.2 镜像规则：Host 与路径前缀要一起换

核心逻辑就三行，但要写成可维护的样子。直接改镜像域名有个问题：镜像站换起来很麻烦，每次都要翻代码。所以我习惯把可变的部分提到文件顶部做成变量。

// 放在 CustomRules.js 文件顶部、函数定义之外 // 镜像站主机名：改成你实测能连通、路径前缀匹配的那一个 var MIRROR_HOST = "mirror-a.example.edu.cn"; // 路径前缀映射：官方是 /online/，镜像站多数是 /qt/online/，少数是 /qtproject/online/ var MIRROR_PATH_FROM = "/online/"; var MIRROR_PATH_TO = "/qt/online/";

然后是函数体：

static function OnBeforeRequest(oSession: Session) { // 只拦 Qt 官方下载域名，别把整机流量都带偏 if (oSession.HostnameIs("download.qt.io") && oSession.PathAndQuery.StartsWith("/online/")) { // 改 Host 头，让请求实际打到镜像站 oSession.hostname = MIRROR_HOST; // 改路径前缀，镜像站的目录结构和官方不一样，必须跟着换 oSession.PathAndQuery = oSession.PathAndQuery .Replace(MIRROR_PATH_FROM, MIRROR_PATH_TO); // 打日志，方便在 Fiddler 的 LOG 面板确认规则到底有没有命中 FiddlerObject.log("[QT-MIRROR] " + oSession.PathAndQuery); } }

逐行说一下为什么这么写。

HostnameIs("download.qt.io")是精确匹配 Host，不做子域通配。这个判断很重要，因为 Fiddler 是全局接管，不加这个条件，你浏览器的所有请求都会被卷进来，规则一改整个机器的上网都受影响。

PathAndQuery.StartsWith("/online/")是第二道过滤。Qt 安装器的下载请求全部落在/online/这个前缀下，元数据请求和归档文件请求都是。加了这个条件，就算以后download.qt.io上出现别的路径，也不会被误改。

oSession.hostname = MIRROR_HOST改的是 Host 头，Fiddler 会按新的 Host 重新解析、重新建连接。注意这里是hostname全小写，不是Hostname。

PathAndQuery.Replace(...)只替换第一处匹配的前缀。Qt 的路径形如/online/qtsdkrepository/windows_x86/desktop/qt5_5150/...，替换完变成/qt/online/qtsdkrepository/...，剩下的部分原样保留，正好对上镜像站的目录结构。

路径前缀这一层是最容易翻车的。国内镜像站同步 Qt 的目录布局并不统一，有的把内容放在/qt/online/下，有的放在/qtproject/online/下。选错前缀的表现是镜像站返回 404，而安装器那边只提示一句「下载失败」，完全看不出是路径问题。我一般的做法是先在浏览器里手动拼一个 url 试通，再写进规则。

表里三个槽位是给人换的，不是同时开。规则里一次只保留一个MIRROR_HOST生效，其余注释掉。一开始我想省事把三条规则都写上，用if / else if串起来——问题在于它们判断条件完全一样，第一条命中后面永远走不到，调试时看到日志只有一条，还以为是规则没生效。

3.3 保存生效与命中确认

改完Ctrl+S保存，Fiddler 会自动重新加载脚本，不需要重启。判断规则有没有生效，看两个地方。

第一个是 LOG 面板。Fiddler 界面上方有一排标签，其中一个是 LOG，FiddlerObject.log()打出来的内容都在这儿。启动安装器以后，如果规则命中了，这个面板会滚动出现[QT-MIRROR]开头的行，后面跟着改写后的路径。一行都没有，说明规则压根没进if分支。

第二个是会话列表。默认情况下 Fiddler 显示的是原始 Host，改写之后列表里download.qt.io会变成镜像站的域名。如果看到 Host 还是download.qt.io，先用 QuickExec 过滤一下：在左下角的黑框里敲select download.qt.io回车，会把相关会话全选中，再看它们的 Host 列。

还有一个判断技巧：在浏览器里直接访问http://download.qt.io/online/，正常应该返回一段 XML 或者 404。如果 Fiddler 开着且规则生效，这个请求会被改写到镜像站，返回值会变成镜像站的内容。拿这个做一次快速验证，比装到一半发现问题再回头查省事得多。

规则验证通过之后，把 Fiddler 留着别关，直接进下一章。安装器必须和 Fiddler 同时在线，任何一个先退出，后续请求就会打回官方源，又会慢下来——注意，这里慢下来只是慢，不会立刻报错，所以很容易被误判成「镜像没起作用」。

4. 分批装组件：先最小集，再用「更改」少量多次补

规则配好了，理论上安装器已经能从镜像拉文件了。但只解决这一层还不够，因为镜像再快，一次要拉的量摆在那儿，安装器自己的内存和缓存撑不住照样崩。这一章说的是第二件事：把一次大安装拆成好几轮小安装。

4.1 第一轮只勾一个编译套件

双击运行qt-unified-windows-x86-3.2.3-online.exe，会先过一个账号页。这一步如果卡住不动，说明元数据没拉下来，回头检查 Fiddler 和规则。

登录之后是组件选择页，树形结构，下面挂着一堆分类。这一页是整个流程里最关键的一步，第一次装的人容易在这里贪多，看到什么勾什么，然后就没有然后了。

第一轮的原则：只勾一组能让你写代码、能编译的最小集。

具体到 5.15.0：

• 展开Qt→Qt 5.15.0，勾其中的MinGW 8.1.0 64-bit。这个是一个完整的编译环境，包含 Qt 库和对应的编译器配套。
• 展开Developer and Designer Tools，勾MinGW 8.1.0 64-bit。这一项是编译器本体，在上一项里有时候会自动带出来，但独立装一次更保险。
• Developer and Designer Tools里的Qt Creator也一并勾上，体积不大，但没有它后面没法开工程。

其余的一律不勾。Sources、Qt Debug Information Files、Qt WebEngine、Qt Charts这些先放着，后面用「更改」补。

选完点下一步，会看到一个许可协议页，勾上同意，再下一步就是下载安装。这一轮的总体积在几个 G 的量级，比勾满要小一个数量级，正常情况下是能跑完的。

安装过程中的观察点：进度条是按单个文件走的，会出现「正在下载 xxx」然后百分比跳动。如果某一段长时间不动，看 Fiddler 的会话列表，有没有一条请求挂在那里没返回。有的话，说明镜像那一段网络卡了，可以等，也可以取消重来——第一轮体量小，重来的代价可以接受。

4.2 后续每轮走维护工具的「更改」入口

第一轮装完，安装器会把信息注册到系统的「程序和功能」里。后面补组件有两条路。

第一条是控制面板：控制面板 → 程序和功能 → 找到Qt 5.15.0→ 右键「更改」。这会拉起维护工具，界面和安装器基本一样，但会读本地的组件状态，已经装好的会标成已安装。

第二条是直接运行维护工具：C:\Qt\MaintenanceTool.exe，或者你自定义安装目录下的同名文件。效果一样，少点几次鼠标。我一般用这条，因为路径固定，不用每次翻控制面板。

进去之后选「添加或移除组件」，会重新拉一次元数据（这一步同样走 Fiddler，规则还得开着），然后回到熟悉的树形选择页。这时候只勾这一轮要装的东西，装完点完成，退出，再重新打开做下一轮。

每轮勾多少？我的经验是 3 到 5 个组件，或者总量控制在第一轮的六七成以内。超过这个量，安装器中途崩掉的概率明显上升。这个数字没有理论依据，纯粹是反复试出来的——同一台机器、同一个镜像，勾 3 个能跑完，勾 8 个大概率在某一段挂掉。

每一轮结束之后不要立刻开下一轮，先把 Fiddler 的会话列表清一下（Ctrl+X），再重新打开维护工具。会话堆到几万条的时候，Fiddler 自己也占内存，和安装器抢资源，等于给自己加难度。

4.3 组件顺序与体量对照

顺序上有讲究，大的往后放。理由很直白：前几轮成功率高，先把能用的环境搭起来；越到后面越难装的，失败了也不影响已经装好的部分。

第三轮装 WebEngine 的时候特别注意：这一轮很可能是全场最容易失败的一轮，因为它的归档包数量多、单个文件也大。如果连着失败两次，别硬刚，换个镜像槽位再试。我在两个镜像上试过同一个组件，一个每次到后半段断，另一个一次过，纯粹是镜像侧同步状态和带宽的差别。

全部装完之后，D:\Qt下面应该是这个样子：

D:\Qt\ ├── 5.15.0\ │ └── mingw81_64\ # Qt 库和 qmake ├── Tools\ │ ├── mingw810_64\ # 编译器本体 │ └── QtCreator\ # IDE └── MaintenanceTool.exe

目录名对不上的时候，先别急着怀疑装坏了，可能是安装器按组件版本号自动命名的，看5.15.0下面实际有几个子目录就能确认。

5. 避坑排查：29% 卡死、镜像 404、Kit 缺失的现场处理

这一章是前面几章攒下来的现场记录，按现象、原因、解决三段来写。遇到问题先在这里对号，对不上再去翻日志。

5.1 下载阶段：卡在固定百分比和内存吃满

现象一：进度停在 29% 左右不动，几分钟后安装器窗口直接消失，任务管理器里进程一起没了。

原因是这一轮要拉的归档文件总量超出了单次会话能承受的范围，而 Fiddler 默认会把经过的响应体缓存在内存里，几十上百个几百兆的包叠在一起，进程内存顶到上限之后被系统干掉，表现出来就是窗口闪退。29% 这个数字不是固定的，取决于你勾了多少组件，勾得多可能 20% 就挂，勾得少能到 40%。解决方式是回到第 4 章，把组件拆成多轮，每轮 3 到 5 个；同时在 Fiddler 里定期Ctrl+X清空会话列表，别让缓存越堆越高。

现象二：安装器提示「无法连接到服务器」，但 Fiddler 里一条相关会话都没有。

原因是安装器根本没走 Fiddler。可能是 Fiddler 启动顺序反了——先开了安装器再开 Fiddler，安装器启动时读到的系统代理配置里还没有 Fiddler。正确顺序是先开 Fiddler，确认它已经接管（随便打开个网页看左栏有没有会话进来），再启动安装器。另一个可能是机器上有别的网络工具抢了系统代理设置，先把它关掉。

5.2 镜像与规则层：404 和规则不生效

现象三：Fiddler 里能看到改写后的请求，但返回 404，安装器提示下载失败。

原因是路径前缀和镜像站的目录布局不匹配。国内镜像同步 Qt 的方式不统一，有的放在/qt/online/下，有的放在/qtproject/online/下，还有的只同步了部分架构目录。判断方法很简单：把 Fiddler 里那条 404 请求的完整 URL 复制出来，直接贴到浏览器地址栏，能打开说明是安装器这边的问题，打不开就是镜像路径错了。解决方式是换MIRROR_PATH_TO的取值，或者直接换下一个镜像槽位。换完记得Ctrl+S保存，Fiddler 会自动重载。

现象四：改完规则，LOG 面板一条[QT-MIRROR]都没有。

原因有三个层次。最外层是规则写错了函数，写到OnBeforeResponse里去了，那个钩子在响应返回之后才触发，改不了请求。中间层是文件没保存，Ctrl+R打开编辑器改完不按Ctrl+S，改动只在编辑器内存里。最里层是条件判断没命中，PathAndQuery不以/online/开头，比如元数据请求走的是别的路径。解决方式是先看函数名对不对，再看文件保存时间，最后在if外面加一行无条件的FiddlerObject.log(oSession.fullUrl)，把所有请求都打出来，看看真实的路径长什么样。这行日志调试完记得删掉，不然会话多了会拖慢 Fiddler。

现象五：规则生效了，下载也跑起来了，但速度还是很慢。

先看 Fiddler 里的响应时间，如果每条请求都要几秒才返回，说明镜像本身慢，换槽位。如果响应很快但总时长还是很长，说明是文件多而不是单个慢，这种情况靠分批解决，不是规则能救的。还有一种情况是规则只对部分请求生效——download.qt.io的某些子路径走了别的域名，比如静态资源放在 CDN 上，这种需要在规则里再加一条HostnameIs判断。

5.3 安装收尾：Kit 缺失和代理残留

现象六：装完了，Qt Creator 里新建工程提示「未找到编译器」，Kit 列表里只有一个红色的感叹号。

原因是只装了 Qt 库，没装编译器本体。Qt 5.15.0 的 MinGW 套件和编译器是分开的两项，在组件树里一个在Qt 5.15.0下面，一个在Developer and Designer Tools下面。漏了后者，库是齐的，但没有g++，Kit 自然识别不到。解决方式是打开维护工具，补装Developer and Designer Tools → MinGW 8.1.0 64-bit，装完重启 Qt Creator，在「工具 → 选项 → Kits」里检查一下，编译器那一栏应该有自动检测到的路径，没有就手动指到D:\Qt\Tools\mingw810_64\bin\g++.exe。

现象七：Qt 装完了，浏览器上不了网。

原因是 Fiddler 退出时没恢复系统代理设置，系统里还留着一条指向本机回环地址的配置。解决方式是打开「Internet 选项 → 连接 → 局域网设置」，把「为 LAN 使用代理服务器」的勾去掉。预防的办法是在 Fiddler 的 Tools → Options → Connections 里，把「Act as system proxy on startup」取消勾选，改成手动在需要的时候开。我现在的习惯是装完 Qt 第一件事就是检查这个，比等浏览器打不开再回头查省心。

6. 装完怎么验证：从 qmake -v 到一个能跑的最小 Demo

装完不等于装对，这一步必须走。验证分三层，一层比一层能说明问题。

第一层，命令行确认版本。开一个 cmd 或者 PowerShell，直接调绝对路径，别依赖 PATH：

# 确认 qmake 指向的是 5.15.0，而不是系统里残留的其它版本 D:\Qt\5.15.0\mingw81_64\bin\qmake.exe -v

正常输出两行，第一行是QMake version 3.1，第二行是Using Qt version 5.15.0 in D:/Qt/5.15.0/mingw81_64/lib。第二行末尾的路径必须是这一轮装的目录，如果不是，说明系统里还有别的 Qt 在 PATH 里抢先，先把 PATH 里旧的删掉。

第二层，编一个最小工程。建个目录，写一个只有窗口的main.cpp和一个.pro：

# 建工程目录 mkdir D:\work\hello-qt && cd /d D:\work\hello-qt # 生成 Makefile D:\Qt\5.15.0\mingw81_64\bin\qmake.exe hello-qt.pro # 编译，-j4 按 CPU 核心数调整 D:\Qt\Tools\mingw810_64\bin\mingw32-make.exe -j4

.pro里只写QT += widgets和SOURCES += main.cpp就够。qmake这一步考的是库文件全不全，mingw32-make这一步考的是编译器通不通。两步都过，说明库和工具链是配对的。只过第一步不过第二步，多半是编译器版本和 Qt 库版本不匹配，比如库是 MinGW 8.1 编的，编译器却是 7.3。

第三层，windeployqt验证依赖完整：

# 把运行时依赖拷到 exe 旁边，能跑起来说明依赖齐全 D:\Qt\5.15.0\mingw81_64\bin\windeployqt.exe hello-qt.exe

这一步会把Qt5Core.dll、Qt5Gui.dll、platforms\qwindows.dll这些拷到 exe 同级目录。拷完双击 exe，能弹出一个空窗口，整套环境就算真的跑通了。跑不起来、提示缺 dll，回头看上一步的编译产物是不是 64 位、和 dll 位数是否一致。

最后补一句习惯上的事。从那以后我每次装完 Qt，都会强制走一遍这三层验证，哪怕只是补装一个Qt Charts——补装最容易把原有的 Kit 配置打乱，改完不验证，等第二天开工程才发现编译不过，就得重新翻一遍前面所有的环节。这套流程本身不复杂，麻烦的是中间任何一步出问题都会伪装成「网络不好」，不做验证根本分不清是装坏了还是没装完。希望帮到你。

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