简介面向首次接触 Qt 5.15.0 在线安装的开发者与运维人员这份 PDF 文档聚焦官方源下载缓慢、安装程序易崩溃及镜像下载数据量过大等常见障碍提供可复用的代理配置思路与分模块安装方案适合需要搭建 Qt 开发环境的中级读者参考。压缩包内仅含 1 个 PDF 文件大小约 833KB篇幅精炼便于离线保存和快速查阅。相关页面显示已有 12109 人学习说明该问题在 Qt 环境部署中具有较高共性。文档围绕 Fiddler 4 规则设置、国内镜像站点切换以及先装基本模块再按需增补组件的处理逻辑展开能帮助读者理解失败原因、定位卡在下载阶段的症结并形成自己的排错路径。读者可从中获得一份轻量的问题分析记录和解决思路参考用于对照排查在线安装中的网络与稳定性问题。1. 卡在 29% 的在线安装QT 5.15.0 装不上的那个瞬间关于 QT 5.15.0 在线安装我见过最典型的现场是这样的进度条走到 29% 左右突然停住硬盘灯狂闪任务管理器里安装器内存一路涨到两三个 G然后窗口直接消失连个错误弹窗都不给。重启再装一遍还是 29%连停顿的位置都一模一样。有人换成国内镜像站重试报错换了个面孔变成Cannot download archive或者Network error while downloading。这类故障最折腾人的地方是它不给错误码只给一个百分比——你无法从界面判断到底是网络断了、文件坏了还是安装器自己撑不住了。这篇笔记面向的是已经拿到 qt-unified 在线安装器、却反复失败在中间某个百分比的开发者从根因往下拆到能照着敲的命令和规则脚本。2. 把请求改写到镜像站Fiddler 4 规则写错一个字符就白忙在线安装器之所以慢是因为它的组件索引和每一个组件包都指向官方源。官方源在国内的连通性时好时坏几十兆的小包还能勉强拖下来几百兆的大包就经常断在半路。所以第一步一定是把请求导向镜像站。但很多人在这一步就翻车hosts 改了域名指向镜像站了安装器却照样卡住或者吐 404。原因不在域名在路径。2.1 光改 hosts 为什么没用域名变了路径没变Qt 的在线仓库结构是这样的安装器先去取一份仓库索引Updates.xml再按索引里记录的相对路径去下载各个组件包。官方源上这个索引位于/online/qtsdkrepository/...下面而这个/online/前缀是官方源独有的。镜像站在同步的时候通常会把整个 Qt 仓库挂在/qt/或者/qtproject/这样的子目录下于是同一份索引在镜像站上的真实地址变成了/qt/online/qtsdkrepository/...。hosts 只能改域名改不了 URL 里的路径。你把download.qt.io指到镜像站的 IP请求路径依然是/online/...镜像站上没有这个路径返回 404安装器拿不到索引就直接报下载失败。所以必须有一个能在 HTTP 层同时改写 host 和 path 的工具Fiddler 4 的OnBeforeRequest就是干这个的。这也是为什么原始方案里宁可绕一圈用抓包工具也不走 hosts——路径前缀这一关hosts 根本过不去。顺带说一句新版安装器其实支持-mirror参数可以直接指定仓库地址比改写请求干净得多# 直接用镜像地址启动在线安装器先看这个参数认不认 qt-unified-windows-x86-3.2.3-online.exe --mirror https://mirror-a.example.edu.cn/qt/参数说明--mirror后面跟的是镜像站的仓库根地址注意末尾要带斜杠且这个根地址要能直接拼上online/qtsdkrepository/...并返回 200。如果你的安装器版本不认这个参数表现为启动后依然去连官方源再回到 Fiddler 改写这条路两者不要同时开否则请求会被改两次。2.2 OnBeforeRequest 规则三段改写缺一不可Fiddler 4 装好后打开菜单栏Rules→Customize Rules快捷键 CtrlR会打开CustomRules.js。用 CtrlF 搜OnBeforeRequest或者按原始笔记里说的从工具栏的 GO 下拉直接跳到这个函数。然后把下面这段塞进去// Fiddler 4 - Rules - Customize Rules - OnBeforeRequest static function OnBeforeRequest(oSession: Session) { // 只改造发往 Qt 官方在线仓库的请求别误伤其它流量 if (oSession.HostnameIs(download.qt.io) oSession.PathAndQuery.StartsWith(/online/)) { // 第一段换域名 oSession.hostname mirror-a.example.edu.cn; // 第二段补上镜像站的路径前缀 // 官方是 /online/xxx镜像站可能是 /qt/online/xxx 或 /qtproject/online/xxx oSession.PathAndQuery oSession.PathAndQuery.Replace(/online/, /qt/online/); // 第三段调试用把改写结果打到日志里确认规则真的命中了 FiddlerObject.log(REWRITE - oSession.hostname oSession.PathAndQuery); } }这三段分别管三件事oSession.hostname决定这条请求最终连哪台服务器oSession.PathAndQuery决定请求的是镜像站上的哪个文件注意它是包含查询串的完整路径用Replace而不是赋值是为了保留后面那串qtsdkrepository/...FiddlerObject.log是给自己看的黑匣子规则有没有命中看日志比看安装器界面快十倍。几个容易踩的细节HostnameIs是大小写不敏感的精确匹配别写成Contains否则会把download.qt.io.evil.example这类也一起改了StartsWith(/online/)里的斜杠不能省省了会把/online2/之类误匹配进来改完必须按 CtrlS 保存Fiddler 会即时生效不用重启但如果你开着旧的安装器进程得让它重新发起请求才会走新规则。2.3 路径前缀对不上是 404 的唯一来源不同镜像站同步 Qt 仓库时挂载的根目录不一样这是最容易让人怀疑人生的地方——域名换成另一个镜像站规则一字未改突然就能装了或者突然全 404。对照下面这张表确认你用的镜像站属于哪一类镜像站挂载方式域名占位示例/online/应替换为直接挂 Qt 仓库到/qt/mirror-a.example.edu.cn/qt/online/挂 Qt 项目目录到/qtproject/mirror-b.example.edu.cn/qtproject/online/只同步了发布版归档mirror-c.example.edu.cn无在线仓库不适用判断方法很简单用 curl 探一下索引文件在不在返回 200 就是对的404 就是前缀错了或者这个镜像站压根没同步在线仓库# 探测镜像站上是否存在 Qt 5.15.0 的在线仓库索引 curl -I --max-time 10 \ https://mirror-a.example.edu.cn/qt/online/qtsdkrepository/windows_x86/desktop/qt5_5150/Updates.xml返回头里的状态码是第一判断依据。如果这里是 404那么无论规则脚本写得多漂亮安装器都只会给你Cannot download archive。有些镜像站只同步了official_releases下的离线包压根没有online目录这种站只能用来下离线安装器做不了在线安装的源早换早省事。2.4 规则生效了没三条验证路径改完规则不等于生效我一般按这三步确认任何一步不通就停下来修不要带着疑问往下装。第一步Fiddler 左侧会话列表里看 Host 列。正常的在线安装过程你会看到大量download.qt.io的请求如果规则生效这些请求在列表里的 Host 仍然显示原始域名因为改写发生在发出之前但你可以打开任意一条看右侧Inspectors→Headers里的实际请求行路径应该已经变成/qt/online/...。第二步看日志。FiddlerObject.log输出的内容会出现在 Fiddler 底部的 Log 标签页里如果你看到成片的REWRITE -说明规则命中一条都没有说明 HTTPS 解密没开Fiddler 只能看到 CONNECT 隧道压根看不到内层 URL规则里的PathAndQuery是空的判断自然不成立。第三步也是最关键的一步确认 HTTPS 解密已开启。Tools→Options→HTTPS勾选捕获并解密 HTTPS 流量Fiddler 会提示安装根证书装完重启 Fiddler。没做这一步前面所有规则都是空转——安装器走的是 HTTPS你看得到连接、看不到路径改写的if条件永远为假。注意装完证书后如果安装器仍然报证书校验失败多半是安装器自带的证书链不认 Fiddler 的根证书此时优先改用--mirror参数而不是继续在抓包工具上叠配置。3. 下载到一半就崩真正的天花板是单次数据量把请求成功导到镜像站之后很多人会迎来第二个更隐蔽的失败装到某个百分比Fiddler 进程内存爆掉或者安装器无声退出。原始笔记里提到 Fiddler 4 会耗尽内存、通常卡在 29%这个观察非常准确而且它指向的根因跟网络质量关系不大——是单次会话要处理的数据量超过了工具和进程能承受的上限。3.1 29% 这个数字是怎么来的Qt 的在线安装器按组件包逐个下载进度条的分母是所有已选组件包的总大小。排在最前面的是索引文件和几个小体积的元数据包下载很快进度蹭蹭往上涨涨到二三十左右就轮到qtbase这类几百兆的大包了。这个位置在不同机器上略有差异但大体都落在同一个区间因为组件包的排列顺序是固定的。于是 29% 就成了一个心理上的“死亡百分比”它既不是网络断了前面小包都下来了也不是磁盘满了而是安装器开始拉大包的那一刻链路上每一环的承载能力同时见底。Fiddler 4 是 32 位进程默认会把每一条会话的完整响应体留在左侧列表里几十个上百兆的包累积下来内存直接顶到 2GB 上限进程被杀安装器这边连接一断重试几次拿不到完整包就自己退出了。顺着这个根因往下推能得出两个结论第一抓包工具只负责改写请求不该让它顺带当缓存服务器第二单次安装的组件数量必须压下来让每一轮的下载总量落在安全区间内。先解决第一条装的过程中定期清会话Fiddler 4 界面操作非脚本 1. 安装开始前Rules - Performance - 取消勾选 Enable Session Caching避免响应体常驻 2. 安装进行中每隔几分钟按 CtrlX 清空左侧会话列表释放已完成的响应体 3. 更彻底Filters 标签页只保留 Host 包含目标镜像站的会话其余不记录这几步不改变安装结果只降低 Fiddler 自己的内存占用。经验值是清得越勤能撑到的百分比越靠后但如果组件总量不变最后还是会撞墙。所以要配合第二条。3.2 少量多次先装一个能跑的最小集原始笔记里的核心解法就是这句“先安装基本模块再在控制面板中采用更改方式增加模块少量多次”。第一轮只勾最小可用集目标是装完之后能打开 Qt Creator、能建工程、能编译出一个空窗口。具体勾选可以是一个编译器套件MSVC 或 MinGW 二选一别两个都勾、Qt Creator、对应版本的 Qt 基础库。源码包、调试符号、示例、附加模块全部先放一边。这一轮的下载量通常只有完整安装的几分之一绝大多数情况下能一口气跑完。跑完之后你的机器上就有了一个完整可用的 Qt 环境后面再怎么折腾至少有一个能编译的基线在那儿不至于全盘重来。3.3 用 MaintenanceTool 增量添加组件第一轮装完安装目录根部会多出一个MaintenanceTool.exe这是后续所有组件增删的入口。原始笔记里说的是在控制面板里选 Qt 然后点“更改”走的其实就是这个工具。# 进入 Qt 安装根目录用维护工具打开组件管理器 cd D:\Qt .\MaintenanceTool.exe打开后选“添加或移除组件”勾上这一轮想补的模块确认然后让它在后台跑。这里有两个要点一是每轮只加一到两个大模块加完等它彻底结束再开下一轮二是维护工具同样会去连官方源所以 Fiddler 规则要保持开启否则这一轮又会退回到慢速下载。如果维护工具界面提示网络错误直接给它带参数启动# 给维护工具也指定镜像根地址绕开默认的官方源 .\MaintenanceTool.exe --mirror https://mirror-a.example.edu.cn/qt/参数含义和在线安装器一致指向镜像站仓库根目录。这条命令在 Fiddler 规则失效或者你不想一直开着抓包工具时特别有用属于那种“知道一次就再也不会忘”的后手。3.4 中断后的残留包不清掉会反复校验失败安装中断之后安装器会把已经下载了一部分的包留在临时目录里。下一次启动时它会尝试续传但这些半截文件在镜像站和官方源之间切换过之后大小和校验值经常对不上于是表现出一模一样的报错The file ... is not a valid archive或者校验和不匹配。很多人以为是镜像站坏了其实是本地缓存脏了。清理方式是按安装器日志里给出的路径去删。安装器每次运行都会在系统临时目录下写一份日志文件名类似qt-unified-windows-x86-3.2.3-online-时间戳.log里面记录每一个下载包的落地路径和最终校验结果。打开它搜error或checksum把报错那一行提到的目录整个删掉再重跑安装成功率会明显不一样。提示清缓存这一步在跨镜像站切换时尤其必要。A 站下了一半换 B 站缓存里的半截包几乎必然导致校验失败报错看起来像网络问题实质是本地文件问题。4. 增量安装的常见问题组件灰掉、反复重下、装完打不开少量多次这套打法本身没问题但拆成多轮之后会冒出一批单轮安装时根本遇不到的问题。下面四条是我在一台机器上完整走完整个流程时记下来的每条都按现象、原因、解决三步写对上号了直接照做。4.1 现象点“更改”进去想装的组件全是灰的原因通常有两个。第一种是版本不匹配你已经装了 5.15.0 的 MinGW 套件现在想再加一个 MSVC 套件但维护工具只列出与当前已装版本严格对应的组件跨大版本或者跨套件的组件在某些安装器版本里会被置灰。第二种是仓库索引没拉全维护工具只拿到了部分组件的元数据没出现在索引里的组件一律显示为不可选。解决办法是先在维护工具里刷新一次仓库再不行就带--mirror参数重启如果确认是这个安装器版本对组件做了限制直接重新跑一次在线安装器在安装目录上做覆盖安装并勾上新组件效果等同于“更改”只是多花一次索引下载的时间。4.2 现象每一轮增量安装都从 0% 重新下大包原因是你上一轮装完之后临时目录被系统清理了或者你在清理磁盘时顺手把安装器的缓存目录清空了。安装器本身不做跨轮次的包复用每轮的下载都是独立的。这不是故障是设计如此。解决办法没有捷径只能控制每轮的量。如果发现某个模块单轮就是下不完把它进一步拆开——比如附加模块里有多个子目录分两轮勾。另外把 Fiddler 的会话列表清空频率调高一点让工具端先别崩剩下的交给安装器自己的重试。4.3 现象装完之后双击 MaintenanceTool 提示无法连接原因是维护工具启动时会先去官方源校验一次组件清单这一步跟 Fiddler 规则是否生效无关是它自己的启动流程。Fiddler 关掉之后这一步直接卡死界面上就一句“无法连接服务器”看起来像安装坏了。解决办法是永久性地给它加参数或者保持改写规则常开。更省事的做法是在安装目录下建一个批处理内容是带--mirror的启动命令以后所有组件增删都从这个批处理走。这属于一次配置、长期受益的事值得花两分钟做掉。4.4 现象全部装完qmake 在命令行里找不到原因有两个层次。表层原因是 Qt 的 bin 目录没进 PATH安装器不会自动帮你配环境变量。深层原因是如果你装了两套以上 Qt比如同时有 5.15 和更新版本PATH 里先进去的那套会赢命令行敲qmake -v出来的版本可能跟你以为的不是同一个。解决时先用绝对路径确认文件存在再决定怎么配# 确认目标版本的 qmake 真实存在 D:\Qt\5.15.0\msvc2019_64\bin\qmake.exe -v # 输出应包含 Using Qt version 5.15.0确认无误后再把这个目录加进 PATH配 PATH 的时候把目标版本的 bin 目录放在其它 Qt 版本前面改完开一个新的终端窗口验证旧的终端不会重新读环境变量这点经常被忽略白白怀疑配置没生效。5. 能编译却跑不起来架构、路径与运行库的收尾排查安装问题解决之后还有一类故障会紧接着出现工程能编译通过但生成的可执行文件双击就闪退或者在 Qt Creator 里点运行没有任何反应。这类问题跟安装过程无关但它的根因往往埋在安装阶段的选择里所以放在一起看。5.1 双击 exe 闪退缺的是运行库不是 Qt 本身这是最经典的一条。你在 Qt Creator 里点运行能跑是因为 Creator 帮你把 bin 目录塞进了进程的搜索路径你直接双击 exe系统只会在当前目录和 PATH 里找依赖的 DLL找不到就静默退出。Qt 的核心库、平台插件、编译器的运行时库一个都不能少。标准做法是用windeployqt把依赖一次性拷到 exe 旁边# 先建一个空目录把编译产物放进去再对这个 exe 执行部署 mkdir D:\deploy\demo copy D:\build-demo\release\demo.exe D:\deploy\demo\ # 用对应套件的 windeployqt 处理依赖注意路径要指向你实际安装的编译器套件 D:\Qt\5.15.0\msvc2019_64\bin\windeployqt.exe --release D:\deploy\demo\demo.exe--release告诉工具按发布模式挑选库如果你编译的是 Debug 版本换成--debug。执行完之后目录里会多出platforms、styles等子目录和一批 DLL这时候再双击 exe 通常就正常了。如果还是闪退用命令行运行一次 exe把标准错误输出抓下来缺哪个 DLL 会直接写在控制台里。5.2 32 位套件与 64 位套件混装安装时同时勾了 MinGW 32 位和 MSVC 64 位是很容易发生的事——反正都是 Qt看起来没区别。但一旦混装Qt Creator 里的 Kit 会变多新建工程时如果选错 Kit编出来的东西跟第三方库的架构对不上链接阶段报一堆unresolved external或者运行期直接崩在没有任何提示的地方。排查的第一步是把 Kit 和套件的对应关系弄清楚别靠猜# 逐套件确认版本与安装前缀输出里能看出是不是同一个 Qt 根目录 D:\Qt\5.15.0\mingw81_64\bin\qmake.exe -query QT_INSTALL_PREFIX D:\Qt\5.15.0\msvc2019_64\bin\qmake.exe -query QT_INSTALL_PREFIX两条命令输出的路径应该分别指向各自的套件目录。如果它们指向同一处说明你的安装有覆盖或者环境变量串了需要重装其中一套。确认之后在 Qt Creator 的 Kit 设置里把每个 Kit 的编译器、调试器、Qt 版本三项一一对应好这一步对上了后面大半的“玄学编译错误”都会消失。5.3 安装路径带中文或空格Qt 的工具链对路径的宽容度比想象中低。安装在D:\我的软件\Qt这种路径下某些构建步骤会把路径拼进命令行而没有加引号于是在空格或非 ASCII 字符处被截断报错信息通常长这样系统找不到指定的路径或者干脆是一个毫无上下文的构建失败。这类问题的判断方法很直接把工程整体挪到纯英文无空格路径下重新构建一次如果好了就是路径问题不用再往下查。安装目录本身如果已经带中文改起来成本高可以不动安装目录只保证工程目录和构建目录是纯英文——D:\work\demo这种就很好。构建目录尤其容易被忽略Qt Creator 默认把影子构建放在工程同级工程名带中文时构建目录也一起带上了。6. 快速定位这类安装故障三分钟缩小范围装到一半失败、界面只给一个百分比的时候漫无目的地重试是最浪费时间的做法。我现在的习惯是先把故障归到一个明确的类别里再决定往哪个方向修判断依据全在下面这张表里。现象先看哪里大概率原因进度百分比长时间不动网络无流量任务管理器网络列源不通规则未生效或镜像站没同步直接报Cannot download archivecurl 探测索引地址路径前缀错或镜像站没有 online 目录报not a valid archive/ 校验失败安装日志里的落地路径本地缓存里有半截包删掉重来安装器窗口无声消失Fiddler 进程内存单轮下载量过大工具或进程撑爆装完打不开维护工具启动命令是否带镜像参数维护工具启动时会回连官方源校验具体的执行顺序我一般是这样第一步打开安装器日志所在目录按修改时间排最新的那份搜error拿到第一个出错的文件路径第二步用 curl 直接探测这个路径返回 404 就是路径改写的问题返回 200 但超时就是连通性问题第三步如果路径和连通性都没问题就去 Fiddler 的会话列表里看这条请求是不是真的被改写了日志里没有REWRITE记录就回去检查 HTTPS 解密的勾有没有打上。这三步走完绝大多数情况都能定性剩下的只是按类别套用前面几章的具体操作。还有一条血泪经验每改一次规则、每换一个镜像站先只安装一个最小的组件试水别一上来就把全量组件勾满。一轮下来十分钟能省掉一次半小时的无效重试。要是三步走完仍然定不了性把日志里第一条报错的完整文件路径贴出来对着镜像站手工下一下那个文件能不能下、下下来多大两个数字一比问题在哪一层就非常清楚了。这份排查流程和改写的规则脚本我连同每一步的操作截图一起整理成了一份 PDF从规则配置到增量安装的顺序都在里面需要照着复现的可以直接去下载区取。从那以后我每次碰这类在线安装的活都强制先跑一遍 curl 探测索引再动手装哪怕看起来网络一切正常——省下的不是那十分钟是失败之后重新排查的两小时。希望帮到你。本文还有配套的精品资源点击获取 
长河君 · 2026/11/4 3:09:39 · 阅读 1.2k Qt 5.15.0在线安装卡29%：镜像站改写与增量安装排障
简介面向首次接触 Qt 5.15.0 在线安装的开发者与运维人员这份 PDF 文档聚焦官方源下载缓慢、安装程序易崩溃及镜像下载数据量过大等常见障碍提供可复用的代理配置思路与分模块安装方案适合需要搭建 Qt 开发环境的中级读者参考。压缩包内仅含 1 个 PDF 文件大小约 833KB篇幅精炼便于离线保存和快速查阅。相关页面显示已有 12109 人学习说明该问题在 Qt 环境部署中具有较高共性。文档围绕 Fiddler 4 规则设置、国内镜像站点切换以及先装基本模块再按需增补组件的处理逻辑展开能帮助读者理解失败原因、定位卡在下载阶段的症结并形成自己的排错路径。读者可从中获得一份轻量的问题分析记录和解决思路参考用于对照排查在线安装中的网络与稳定性问题。1. 卡在 29% 的在线安装QT 5.15.0 装不上的那个瞬间关于 QT 5.15.0 在线安装我见过最典型的现场是这样的进度条走到 29% 左右突然停住硬盘灯狂闪任务管理器里安装器内存一路涨到两三个 G然后窗口直接消失连个错误弹窗都不给。重启再装一遍还是 29%连停顿的位置都一模一样。有人换成国内镜像站重试报错换了个面孔变成Cannot download archive或者Network error while downloading。这类故障最折腾人的地方是它不给错误码只给一个百分比——你无法从界面判断到底是网络断了、文件坏了还是安装器自己撑不住了。这篇笔记面向的是已经拿到 qt-unified 在线安装器、却反复失败在中间某个百分比的开发者从根因往下拆到能照着敲的命令和规则脚本。2. 把请求改写到镜像站Fiddler 4 规则写错一个字符就白忙在线安装器之所以慢是因为它的组件索引和每一个组件包都指向官方源。官方源在国内的连通性时好时坏几十兆的小包还能勉强拖下来几百兆的大包就经常断在半路。所以第一步一定是把请求导向镜像站。但很多人在这一步就翻车hosts 改了域名指向镜像站了安装器却照样卡住或者吐 404。原因不在域名在路径。2.1 光改 hosts 为什么没用域名变了路径没变Qt 的在线仓库结构是这样的安装器先去取一份仓库索引Updates.xml再按索引里记录的相对路径去下载各个组件包。官方源上这个索引位于/online/qtsdkrepository/...下面而这个/online/前缀是官方源独有的。镜像站在同步的时候通常会把整个 Qt 仓库挂在/qt/或者/qtproject/这样的子目录下于是同一份索引在镜像站上的真实地址变成了/qt/online/qtsdkrepository/...。hosts 只能改域名改不了 URL 里的路径。你把download.qt.io指到镜像站的 IP请求路径依然是/online/...镜像站上没有这个路径返回 404安装器拿不到索引就直接报下载失败。所以必须有一个能在 HTTP 层同时改写 host 和 path 的工具Fiddler 4 的OnBeforeRequest就是干这个的。这也是为什么原始方案里宁可绕一圈用抓包工具也不走 hosts——路径前缀这一关hosts 根本过不去。顺带说一句新版安装器其实支持-mirror参数可以直接指定仓库地址比改写请求干净得多# 直接用镜像地址启动在线安装器先看这个参数认不认 qt-unified-windows-x86-3.2.3-online.exe --mirror https://mirror-a.example.edu.cn/qt/参数说明--mirror后面跟的是镜像站的仓库根地址注意末尾要带斜杠且这个根地址要能直接拼上online/qtsdkrepository/...并返回 200。如果你的安装器版本不认这个参数表现为启动后依然去连官方源再回到 Fiddler 改写这条路两者不要同时开否则请求会被改两次。2.2 OnBeforeRequest 规则三段改写缺一不可Fiddler 4 装好后打开菜单栏Rules→Customize Rules快捷键 CtrlR会打开CustomRules.js。用 CtrlF 搜OnBeforeRequest或者按原始笔记里说的从工具栏的 GO 下拉直接跳到这个函数。然后把下面这段塞进去// Fiddler 4 - Rules - Customize Rules - OnBeforeRequest static function OnBeforeRequest(oSession: Session) { // 只改造发往 Qt 官方在线仓库的请求别误伤其它流量 if (oSession.HostnameIs(download.qt.io) oSession.PathAndQuery.StartsWith(/online/)) { // 第一段换域名 oSession.hostname mirror-a.example.edu.cn; // 第二段补上镜像站的路径前缀 // 官方是 /online/xxx镜像站可能是 /qt/online/xxx 或 /qtproject/online/xxx oSession.PathAndQuery oSession.PathAndQuery.Replace(/online/, /qt/online/); // 第三段调试用把改写结果打到日志里确认规则真的命中了 FiddlerObject.log(REWRITE - oSession.hostname oSession.PathAndQuery); } }这三段分别管三件事oSession.hostname决定这条请求最终连哪台服务器oSession.PathAndQuery决定请求的是镜像站上的哪个文件注意它是包含查询串的完整路径用Replace而不是赋值是为了保留后面那串qtsdkrepository/...FiddlerObject.log是给自己看的黑匣子规则有没有命中看日志比看安装器界面快十倍。几个容易踩的细节HostnameIs是大小写不敏感的精确匹配别写成Contains否则会把download.qt.io.evil.example这类也一起改了StartsWith(/online/)里的斜杠不能省省了会把/online2/之类误匹配进来改完必须按 CtrlS 保存Fiddler 会即时生效不用重启但如果你开着旧的安装器进程得让它重新发起请求才会走新规则。2.3 路径前缀对不上是 404 的唯一来源不同镜像站同步 Qt 仓库时挂载的根目录不一样这是最容易让人怀疑人生的地方——域名换成另一个镜像站规则一字未改突然就能装了或者突然全 404。对照下面这张表确认你用的镜像站属于哪一类镜像站挂载方式域名占位示例/online/应替换为直接挂 Qt 仓库到/qt/mirror-a.example.edu.cn/qt/online/挂 Qt 项目目录到/qtproject/mirror-b.example.edu.cn/qtproject/online/只同步了发布版归档mirror-c.example.edu.cn无在线仓库不适用判断方法很简单用 curl 探一下索引文件在不在返回 200 就是对的404 就是前缀错了或者这个镜像站压根没同步在线仓库# 探测镜像站上是否存在 Qt 5.15.0 的在线仓库索引 curl -I --max-time 10 \ https://mirror-a.example.edu.cn/qt/online/qtsdkrepository/windows_x86/desktop/qt5_5150/Updates.xml返回头里的状态码是第一判断依据。如果这里是 404那么无论规则脚本写得多漂亮安装器都只会给你Cannot download archive。有些镜像站只同步了official_releases下的离线包压根没有online目录这种站只能用来下离线安装器做不了在线安装的源早换早省事。2.4 规则生效了没三条验证路径改完规则不等于生效我一般按这三步确认任何一步不通就停下来修不要带着疑问往下装。第一步Fiddler 左侧会话列表里看 Host 列。正常的在线安装过程你会看到大量download.qt.io的请求如果规则生效这些请求在列表里的 Host 仍然显示原始域名因为改写发生在发出之前但你可以打开任意一条看右侧Inspectors→Headers里的实际请求行路径应该已经变成/qt/online/...。第二步看日志。FiddlerObject.log输出的内容会出现在 Fiddler 底部的 Log 标签页里如果你看到成片的REWRITE -说明规则命中一条都没有说明 HTTPS 解密没开Fiddler 只能看到 CONNECT 隧道压根看不到内层 URL规则里的PathAndQuery是空的判断自然不成立。第三步也是最关键的一步确认 HTTPS 解密已开启。Tools→Options→HTTPS勾选捕获并解密 HTTPS 流量Fiddler 会提示安装根证书装完重启 Fiddler。没做这一步前面所有规则都是空转——安装器走的是 HTTPS你看得到连接、看不到路径改写的if条件永远为假。注意装完证书后如果安装器仍然报证书校验失败多半是安装器自带的证书链不认 Fiddler 的根证书此时优先改用--mirror参数而不是继续在抓包工具上叠配置。3. 下载到一半就崩真正的天花板是单次数据量把请求成功导到镜像站之后很多人会迎来第二个更隐蔽的失败装到某个百分比Fiddler 进程内存爆掉或者安装器无声退出。原始笔记里提到 Fiddler 4 会耗尽内存、通常卡在 29%这个观察非常准确而且它指向的根因跟网络质量关系不大——是单次会话要处理的数据量超过了工具和进程能承受的上限。3.1 29% 这个数字是怎么来的Qt 的在线安装器按组件包逐个下载进度条的分母是所有已选组件包的总大小。排在最前面的是索引文件和几个小体积的元数据包下载很快进度蹭蹭往上涨涨到二三十左右就轮到qtbase这类几百兆的大包了。这个位置在不同机器上略有差异但大体都落在同一个区间因为组件包的排列顺序是固定的。于是 29% 就成了一个心理上的“死亡百分比”它既不是网络断了前面小包都下来了也不是磁盘满了而是安装器开始拉大包的那一刻链路上每一环的承载能力同时见底。Fiddler 4 是 32 位进程默认会把每一条会话的完整响应体留在左侧列表里几十个上百兆的包累积下来内存直接顶到 2GB 上限进程被杀安装器这边连接一断重试几次拿不到完整包就自己退出了。顺着这个根因往下推能得出两个结论第一抓包工具只负责改写请求不该让它顺带当缓存服务器第二单次安装的组件数量必须压下来让每一轮的下载总量落在安全区间内。先解决第一条装的过程中定期清会话Fiddler 4 界面操作非脚本 1. 安装开始前Rules - Performance - 取消勾选 Enable Session Caching避免响应体常驻 2. 安装进行中每隔几分钟按 CtrlX 清空左侧会话列表释放已完成的响应体 3. 更彻底Filters 标签页只保留 Host 包含目标镜像站的会话其余不记录这几步不改变安装结果只降低 Fiddler 自己的内存占用。经验值是清得越勤能撑到的百分比越靠后但如果组件总量不变最后还是会撞墙。所以要配合第二条。3.2 少量多次先装一个能跑的最小集原始笔记里的核心解法就是这句“先安装基本模块再在控制面板中采用更改方式增加模块少量多次”。第一轮只勾最小可用集目标是装完之后能打开 Qt Creator、能建工程、能编译出一个空窗口。具体勾选可以是一个编译器套件MSVC 或 MinGW 二选一别两个都勾、Qt Creator、对应版本的 Qt 基础库。源码包、调试符号、示例、附加模块全部先放一边。这一轮的下载量通常只有完整安装的几分之一绝大多数情况下能一口气跑完。跑完之后你的机器上就有了一个完整可用的 Qt 环境后面再怎么折腾至少有一个能编译的基线在那儿不至于全盘重来。3.3 用 MaintenanceTool 增量添加组件第一轮装完安装目录根部会多出一个MaintenanceTool.exe这是后续所有组件增删的入口。原始笔记里说的是在控制面板里选 Qt 然后点“更改”走的其实就是这个工具。# 进入 Qt 安装根目录用维护工具打开组件管理器 cd D:\Qt .\MaintenanceTool.exe打开后选“添加或移除组件”勾上这一轮想补的模块确认然后让它在后台跑。这里有两个要点一是每轮只加一到两个大模块加完等它彻底结束再开下一轮二是维护工具同样会去连官方源所以 Fiddler 规则要保持开启否则这一轮又会退回到慢速下载。如果维护工具界面提示网络错误直接给它带参数启动# 给维护工具也指定镜像根地址绕开默认的官方源 .\MaintenanceTool.exe --mirror https://mirror-a.example.edu.cn/qt/参数含义和在线安装器一致指向镜像站仓库根目录。这条命令在 Fiddler 规则失效或者你不想一直开着抓包工具时特别有用属于那种“知道一次就再也不会忘”的后手。3.4 中断后的残留包不清掉会反复校验失败安装中断之后安装器会把已经下载了一部分的包留在临时目录里。下一次启动时它会尝试续传但这些半截文件在镜像站和官方源之间切换过之后大小和校验值经常对不上于是表现出一模一样的报错The file ... is not a valid archive或者校验和不匹配。很多人以为是镜像站坏了其实是本地缓存脏了。清理方式是按安装器日志里给出的路径去删。安装器每次运行都会在系统临时目录下写一份日志文件名类似qt-unified-windows-x86-3.2.3-online-时间戳.log里面记录每一个下载包的落地路径和最终校验结果。打开它搜error或checksum把报错那一行提到的目录整个删掉再重跑安装成功率会明显不一样。提示清缓存这一步在跨镜像站切换时尤其必要。A 站下了一半换 B 站缓存里的半截包几乎必然导致校验失败报错看起来像网络问题实质是本地文件问题。4. 增量安装的常见问题组件灰掉、反复重下、装完打不开少量多次这套打法本身没问题但拆成多轮之后会冒出一批单轮安装时根本遇不到的问题。下面四条是我在一台机器上完整走完整个流程时记下来的每条都按现象、原因、解决三步写对上号了直接照做。4.1 现象点“更改”进去想装的组件全是灰的原因通常有两个。第一种是版本不匹配你已经装了 5.15.0 的 MinGW 套件现在想再加一个 MSVC 套件但维护工具只列出与当前已装版本严格对应的组件跨大版本或者跨套件的组件在某些安装器版本里会被置灰。第二种是仓库索引没拉全维护工具只拿到了部分组件的元数据没出现在索引里的组件一律显示为不可选。解决办法是先在维护工具里刷新一次仓库再不行就带--mirror参数重启如果确认是这个安装器版本对组件做了限制直接重新跑一次在线安装器在安装目录上做覆盖安装并勾上新组件效果等同于“更改”只是多花一次索引下载的时间。4.2 现象每一轮增量安装都从 0% 重新下大包原因是你上一轮装完之后临时目录被系统清理了或者你在清理磁盘时顺手把安装器的缓存目录清空了。安装器本身不做跨轮次的包复用每轮的下载都是独立的。这不是故障是设计如此。解决办法没有捷径只能控制每轮的量。如果发现某个模块单轮就是下不完把它进一步拆开——比如附加模块里有多个子目录分两轮勾。另外把 Fiddler 的会话列表清空频率调高一点让工具端先别崩剩下的交给安装器自己的重试。4.3 现象装完之后双击 MaintenanceTool 提示无法连接原因是维护工具启动时会先去官方源校验一次组件清单这一步跟 Fiddler 规则是否生效无关是它自己的启动流程。Fiddler 关掉之后这一步直接卡死界面上就一句“无法连接服务器”看起来像安装坏了。解决办法是永久性地给它加参数或者保持改写规则常开。更省事的做法是在安装目录下建一个批处理内容是带--mirror的启动命令以后所有组件增删都从这个批处理走。这属于一次配置、长期受益的事值得花两分钟做掉。4.4 现象全部装完qmake 在命令行里找不到原因有两个层次。表层原因是 Qt 的 bin 目录没进 PATH安装器不会自动帮你配环境变量。深层原因是如果你装了两套以上 Qt比如同时有 5.15 和更新版本PATH 里先进去的那套会赢命令行敲qmake -v出来的版本可能跟你以为的不是同一个。解决时先用绝对路径确认文件存在再决定怎么配# 确认目标版本的 qmake 真实存在 D:\Qt\5.15.0\msvc2019_64\bin\qmake.exe -v # 输出应包含 Using Qt version 5.15.0确认无误后再把这个目录加进 PATH配 PATH 的时候把目标版本的 bin 目录放在其它 Qt 版本前面改完开一个新的终端窗口验证旧的终端不会重新读环境变量这点经常被忽略白白怀疑配置没生效。5. 能编译却跑不起来架构、路径与运行库的收尾排查安装问题解决之后还有一类故障会紧接着出现工程能编译通过但生成的可执行文件双击就闪退或者在 Qt Creator 里点运行没有任何反应。这类问题跟安装过程无关但它的根因往往埋在安装阶段的选择里所以放在一起看。5.1 双击 exe 闪退缺的是运行库不是 Qt 本身这是最经典的一条。你在 Qt Creator 里点运行能跑是因为 Creator 帮你把 bin 目录塞进了进程的搜索路径你直接双击 exe系统只会在当前目录和 PATH 里找依赖的 DLL找不到就静默退出。Qt 的核心库、平台插件、编译器的运行时库一个都不能少。标准做法是用windeployqt把依赖一次性拷到 exe 旁边# 先建一个空目录把编译产物放进去再对这个 exe 执行部署 mkdir D:\deploy\demo copy D:\build-demo\release\demo.exe D:\deploy\demo\ # 用对应套件的 windeployqt 处理依赖注意路径要指向你实际安装的编译器套件 D:\Qt\5.15.0\msvc2019_64\bin\windeployqt.exe --release D:\deploy\demo\demo.exe--release告诉工具按发布模式挑选库如果你编译的是 Debug 版本换成--debug。执行完之后目录里会多出platforms、styles等子目录和一批 DLL这时候再双击 exe 通常就正常了。如果还是闪退用命令行运行一次 exe把标准错误输出抓下来缺哪个 DLL 会直接写在控制台里。5.2 32 位套件与 64 位套件混装安装时同时勾了 MinGW 32 位和 MSVC 64 位是很容易发生的事——反正都是 Qt看起来没区别。但一旦混装Qt Creator 里的 Kit 会变多新建工程时如果选错 Kit编出来的东西跟第三方库的架构对不上链接阶段报一堆unresolved external或者运行期直接崩在没有任何提示的地方。排查的第一步是把 Kit 和套件的对应关系弄清楚别靠猜# 逐套件确认版本与安装前缀输出里能看出是不是同一个 Qt 根目录 D:\Qt\5.15.0\mingw81_64\bin\qmake.exe -query QT_INSTALL_PREFIX D:\Qt\5.15.0\msvc2019_64\bin\qmake.exe -query QT_INSTALL_PREFIX两条命令输出的路径应该分别指向各自的套件目录。如果它们指向同一处说明你的安装有覆盖或者环境变量串了需要重装其中一套。确认之后在 Qt Creator 的 Kit 设置里把每个 Kit 的编译器、调试器、Qt 版本三项一一对应好这一步对上了后面大半的“玄学编译错误”都会消失。5.3 安装路径带中文或空格Qt 的工具链对路径的宽容度比想象中低。安装在D:\我的软件\Qt这种路径下某些构建步骤会把路径拼进命令行而没有加引号于是在空格或非 ASCII 字符处被截断报错信息通常长这样系统找不到指定的路径或者干脆是一个毫无上下文的构建失败。这类问题的判断方法很直接把工程整体挪到纯英文无空格路径下重新构建一次如果好了就是路径问题不用再往下查。安装目录本身如果已经带中文改起来成本高可以不动安装目录只保证工程目录和构建目录是纯英文——D:\work\demo这种就很好。构建目录尤其容易被忽略Qt Creator 默认把影子构建放在工程同级工程名带中文时构建目录也一起带上了。6. 快速定位这类安装故障三分钟缩小范围装到一半失败、界面只给一个百分比的时候漫无目的地重试是最浪费时间的做法。我现在的习惯是先把故障归到一个明确的类别里再决定往哪个方向修判断依据全在下面这张表里。现象先看哪里大概率原因进度百分比长时间不动网络无流量任务管理器网络列源不通规则未生效或镜像站没同步直接报Cannot download archivecurl 探测索引地址路径前缀错或镜像站没有 online 目录报not a valid archive/ 校验失败安装日志里的落地路径本地缓存里有半截包删掉重来安装器窗口无声消失Fiddler 进程内存单轮下载量过大工具或进程撑爆装完打不开维护工具启动命令是否带镜像参数维护工具启动时会回连官方源校验具体的执行顺序我一般是这样第一步打开安装器日志所在目录按修改时间排最新的那份搜error拿到第一个出错的文件路径第二步用 curl 直接探测这个路径返回 404 就是路径改写的问题返回 200 但超时就是连通性问题第三步如果路径和连通性都没问题就去 Fiddler 的会话列表里看这条请求是不是真的被改写了日志里没有REWRITE记录就回去检查 HTTPS 解密的勾有没有打上。这三步走完绝大多数情况都能定性剩下的只是按类别套用前面几章的具体操作。还有一条血泪经验每改一次规则、每换一个镜像站先只安装一个最小的组件试水别一上来就把全量组件勾满。一轮下来十分钟能省掉一次半小时的无效重试。要是三步走完仍然定不了性把日志里第一条报错的完整文件路径贴出来对着镜像站手工下一下那个文件能不能下、下下来多大两个数字一比问题在哪一层就非常清楚了。这份排查流程和改写的规则脚本我连同每一步的操作截图一起整理成了一份 PDF从规则配置到增量安装的顺序都在里面需要照着复现的可以直接去下载区取。从那以后我每次碰这类在线安装的活都强制先跑一遍 curl 探测索引再动手装哪怕看起来网络一切正常——省下的不是那十分钟是失败之后重新排查的两小时。希望帮到你。本文还有配套的精品资源点击获取