★ FEATURED ARTICLE 简介《完美解决QT 5.15.0在线安装问题》是一份面向Qt开发者的实战排错文档聚焦Qt 5.15.0之后官方改为在线安装所引发的下载缓慢、安装程序频繁崩溃、配置镜像代理后仍在中途失败等典型问题。文档从现象出发梳理数据量大导致的内存耗尽与连接不稳定成因并给出可复用的代理规则配置与分批安装思路适合正在搭建Qt开发环境、或长期卡在安装环节的初中级开发者参考。整个资源包仅含1个PDF文件体积约833KB轻量易取随手保存即可查阅。该文档已有12109人学习下载在同类环境配置问题中具有较高的实用参考价值。读者可从中获得在线安装卡顿与崩溃的完整排查路径、镜像站点切换的规则写法以及通过模块分批安装规避大数据量失败的处理经验便于对照自身环境快速定位症结减少反复重装的试错成本。1. 在线安装器卡在 29%这份 PDF 拆的是“镜像改写 分批补装”两条线晚上十点QT 5.15.0 在线安装器跑到 29% 附近闪退换镜像、重开安装器、清缓存都试过还是卡在同一个位置。这份 PDF 记录的不是单纯“下载慢”的偏方而是把 Fiddler 4 的请求改写规则和“先最小集、再控制面板更改补组件”的少量多次顺序固定下来。它适合还在用 QT 5.15.0 在线安装、又不想一次性勾满组件的人如果你已经能离线包安装这份资料的价值主要在排查思路和规则脚本。反直觉的地方是镜像只解决“从哪拉”不解决“一次拉太多把抓包工具内存打爆”所以规则和分批必须一起用。2. 换镜像为什么仍然失败先看清 QT 5.15.0 在线安装器的请求链2.1 QT 5.15.0 在线安装器到底在拉什么QT 5.15.0 改成在线安装后安装器不是简单下载一个压缩包。它先拉组件索引再按你勾选的组件生成下载队列队列里既有安装器自身需要的元数据也有体积很大的二进制包、源码包、调试信息包。索引文件通常不大真正把时间和内存吃掉的是一批一批的大文件。安装器界面显示的百分比不是“单个文件进度”而是整个队列的合并进度所以卡在 29% 并不代表第 29% 那个文件坏了可能是队列里某个大包连续重试也可能是本机抓包工具的内存已经到顶。我在排查时一般先看 Fiddler 4 的会话列表如果能看到大量qtsdkrepository路径下的请求说明安装器已经进入组件下载阶段如果只看到一排CONNECT没有具体路径说明 HTTPS 解密没有生效后面的路径判断根本不会执行。这个区别很关键因为很多人把规则贴进去后发现“没效果”实际不是规则写错而是抓包工具只看到隧道看不到 URL。常见做法是第一次运行 Fiddler 时按提示信任根证书再重启安装器让请求重新走一遍。还有一个容易忽略的点在线安装器会复用临时目录和缓存。你上一次失败留下的半截文件下一次可能被重新校验、重新续传表面上看是“又卡在 29%”实际是旧缓存和新队列混在一起。我的习惯是每轮安装前先关掉安装器清空 Fiddler 会话列表再确认临时目录没有残留的大文件。不要一边失败一边反复点重试那样只会让会话列表越来越长内存曲线越来越陡。2.2 Fiddler 4 规则改写与镜像路径的对应关系Fiddler 4 的规则核心是两个字段oSession.hostname和oSession.PathAndQuery。前者决定请求发到哪个主机后者决定请求的路径和查询串。项目里的思路是匹配官方下载主机的/online/前缀把主机改成可达镜像站再把/online/替换成镜像站实际目录前缀。听起来简单但镜像站的目录布局并不统一常见有两种一种是/qt/online/...另一种是/qtproject/online/...。这两个前缀不能混用混用的结果就是 404安装器收到 404 后可能重试也可能直接报错退出。官方请求路径形态镜像候选前缀验证方式/online/qtsdkrepository/.../qt/online/qtsdkrepository/...浏览器打开完整镜像 URL看是否返回 200/online/qtsdkrepository/.../qtproject/online/qtsdkrepository/...同上换前缀再试/online/...其他子路径以镜像站目录为准不要只看首页要拼到具体文件上表的重点不是让你背路径而是让你先验证再改规则。我一般会拿安装器会话列表里的一个完整 URL把主机换成镜像站把/online/换成候选前缀直接在浏览器里打开。能返回文件内容或者至少返回 200/206才说明这个前缀可用返回 404 就换另一个前缀不要硬猜。路径里的斜杠、大小写、重复前缀都要逐字对镜像站不会帮你做模糊匹配。规则里的StartsWith(/online/)是第二道保险。它只处理以/online/开头的请求避免把安装器的其他请求也改到镜像站。有人为了“省事”把条件写成包含qt就改写结果登录、校验、更新检查全被带偏安装器直接翻车。血泪经验是规则越窄越安全只改你确认需要改的下载路径其他请求一律放行。2.3 内存峰值是怎么被“一次性全量安装”抬上去的Fiddler 4 会把会话保存在列表里默认还会保留响应体、解码后的内容、时间信息。你勾的组件越多安装器并发或连续发出的请求越多Fiddler 的会话列表就越长内存占用就越高。项目正文里提到“数据量太大Fiddler 会耗尽全部内存也无法下载完成通常在 29% 就可能失败”这个现象在任务管理器里很直观安装器还没报错Fiddler 的内存已经涨到几个 GB随后安装器闪退或者抓包工具无响应。所以“换镜像”只解决了下载源的问题没有解决“一次拉太多”的问题。我的处理顺序是反过来的先只装最小可运行集让安装器走完一轮完整流程确认规则、证书、路径都通再通过控制面板的“更改”逐批补组件。每批只增加一到两个大项安装完关掉 Fiddler清空会话再开下一轮。这样单轮会话数量被压下来内存峰值就不会堆到不可控。少量多次不是玄学它是在给抓包工具和安装器都留出清理窗口。如果你不想频繁开关 Fiddler至少要在每轮开始前手动清空会话列表并关掉响应体预览。常见做法是只保留摘要列不展开大响应安装器下载大包时不要点开会话看内容否则解码和渲染会再吃一层内存。这个细节看起来小但在 29% 附近往往就是压垮进程的最后一根稻草。2.4 安装器版本和系统环境的边界项目里用的安装器是qt-unified-windows-x86-3.2.3-online.exe这个版本号有意义不同版本的在线安装器对维护模式的入口、缓存目录、组件索引的请求路径可能不一样。你拿旧规则套新安装器可能出现路径对不上、维护模式找不到“更改”的情况。我的建议是先把安装器版本固定下来规则、截图、操作顺序都按同一版本来不要一边换安装器一边改规则否则出问题无法判断是规则错还是版本差异。系统环境方面Windows 控制面板里的“更改”依赖安装器注册的卸载/维护信息。如果你把安装目录移动过、用绿色解压方式打开过安装器、或者中途删过注册项控制面板可能找不到 QT 的“更改”入口。这时候不要急着重装系统先用原安装器再跑一次维护模式让它重新注册如果还是不行保留安装器本体和安装目录按第 4 章的批次顺序重新走最小集。权限上安装器和解压目录最好不要放在中文路径或受控目录下避免校验阶段出现莫名其妙的写入失败。注意Fiddler 规则只改写请求地址不替代镜像站本身的目录校验路径前缀错一个字符就会 404安装器重试几次后可能直接退出。3. 把 Fiddler 4 规则写成可抄作业四个参数逐条拆开3.1 打开规则入口与 OnBeforeRequest 的位置Fiddler 4 的规则入口在菜单Rules - Customize Rules打开后会看到CustomRules.js。这个文件通常放在用户文档目录下的Fiddler2\Scripts里改之前先复制一份备份命名成CustomRules.js.bak。备份不是形式主义规则文件里还有 Fiddler 自己的默认逻辑改错一行可能导致所有请求都不正常回滚时直接覆盖备份最快。打开后搜索OnBeforeRequest把改写逻辑放在这个函数里不要放到OnBeforeResponse因为响应阶段请求已经发出去了再改主机和路径没有意义。规则生效前还要确认 HTTPS 解密。Fiddler 第一次运行时通常会提示安装根证书按提示信任后重启 Fiddler。你可以在会话列表里看如果请求的 Host 列显示具体域名、URL 列显示完整路径说明解密生效如果只有CONNECT和隧道信息说明证书没被安装器信任。这个检查顺序不能省否则你会在规则代码里找半天最后发现是证书问题。3.2 规则脚本域名改写、路径前缀、镜像占位// Fiddler 4 - Rules - Customize Rules - OnBeforeRequest // 只改写 QT 在线安装器的下载请求其他请求保持原样 static function OnBeforeRequest(oSession: Session) { var OFFICIAL_HOST download.qt.io; var MIRROR_HOST mirror.example.edu; // 换成你验证可达的镜像站主机名不要带 https:// var MIRROR_PREFIX /qt/online/; // 常见前缀之一按镜像站实际目录调整 var OFFICIAL_PREFIX /online/; // 官方下载路径前缀不要改成 / if (oSession.HostnameIs(OFFICIAL_HOST) oSession.PathAndQuery.StartsWith(OFFICIAL_PREFIX)) { oSession.hostname MIRROR_HOST; oSession.PathAndQuery oSession.PathAndQuery.Replace(OFFICIAL_PREFIX, MIRROR_PREFIX); FiddlerObject.log(QT rewrite: oSession.fullUrl); } }这段代码只做三件事匹配官方主机、匹配/online/前缀、把主机和路径替换成镜像站。OFFICIAL_HOST保持官方下载主机不变用来限定改写范围MIRROR_HOST是占位符必须换成你本机验证过能访问的镜像站主机名不要带协议头MIRROR_PREFIX是最容易错的一项常见有/qt/online/和/qtproject/online/两种选错就是 404OFFICIAL_PREFIX默认/online/不要为了“多匹配一点”改成/否则安装器的其他请求也会被带走。FiddlerObject.log是给排查用的它会把改写后的完整 URL 写到 Fiddler 日志里。你不需要一直开着但在第一次验证时很有用看日志里的 URL 是否包含你设置的镜像前缀主机是否已经变成镜像站。如果日志没有输出说明条件没命中优先检查HostnameIs和StartsWith而不是怀疑镜像站。代码里的Replace只替换第一个匹配项这里路径开头只有一个/online/配合StartsWith是安全的如果你把条件放宽可能会误替换路径中间的同名子串。参数作用怎么改OFFICIAL_HOST限定只改写官方下载主机保持download.qt.io不要换成镜像站MIRROR_HOST指定镜像站主机换成你验证可达的主机名不带https://MIRROR_PREFIX指定镜像站路径前缀按实际目录选/qt/online/或/qtproject/online/OFFICIAL_PREFIX指定官方路径前缀默认/online/不要改成/3.3 规则生效的验证看会话列表和响应码改完规则后不要直接跑完整安装先做一次小验证。清空 Fiddler 会话列表打开安装器走到组件选择页随便勾一个最小项开始下载然后切回 Fiddler 看会话。重点看三列Host 是否变成你设置的镜像主机、URL 是否包含镜像前缀、响应码是否是 200 或 206。206 表示分段下载正常302 表示跳转跟着看最终地址404 表示路径不对回到 3.2 换前缀403 可能是镜像站限制了访问方式换一个可达镜像再试。也可以在浏览器里先验证镜像 URL。下面这条命令只是示例路径要换成你会话列表里实际出现的文件路径主机换成你验证过的镜像站# 示例验证镜像站上的索引文件是否可达 curl -I https://mirror.example.edu/qt/online/qtsdkrepository/windows_x86/desktop/curl -I只发 HEAD 请求看响应头就够。返回 200 说明路径存在返回 404 说明前缀或文件路径不对。不要拿首页地址验证首页能打开不代表组件目录存在也不要只看一次镜像同步可能有延迟隔几分钟再试一次。验证通过后再回到安装器继续不要一边下载一边改规则否则会话列表里新旧请求混在一起很难判断哪条生效。3.4 失败回滚清空规则与恢复 Hosts规则改错后的回滚顺序要固定先注释掉OnBeforeRequest里的改写段保存规则再清空 Fiddler 会话列表然后关闭安装器最后关闭 Fiddler确认系统网络设置没有残留。很多人只关安装器不关 Fiddler下一次请求仍然被旧规则接管误以为“规则删了没生效”。如果你改过系统 hosts 文件也要检查有没有手动添加的镜像映射规则和 hosts 同时存在时排查会变成黑匣子。回滚后先跑一次不启用规则的安装器确认它能正常访问官方源或者至少能走到组件列表。这个基线很重要只有基线正常你才能判断后续失败是规则问题还是安装器本身问题。我的习惯是每改一次规则就在文件名里加日期后缀比如CustomRules-20200802.js出问题直接换回上一版不用靠记忆恢复。规则文件不大但它是整条链路里最容易改错、也最值得留后悔药的地方。4. 少量多次安装的完整操作链先最小集再“更改”补组件4.1 第一次安装只勾最小可运行集第一次跑安装器时不要被组件树吓到先只勾一个桌面 Kit 和 Qt Creator。具体来说QT 5.15.0 下面选一个你确定要用的编译器套件比如 MinGW 或 MSVC 对应的桌面版本再加 Qt Creator 本体。Sources、Debug Info、Android、WebAssembly、附加模块全部先不勾。这样做的目的不是省磁盘而是把第一轮请求数量压到最低让规则、证书、镜像路径在一个可控范围内跑通。第一轮能走完说明链路是通的第一轮就勾满失败了你根本不知道是哪个组件的请求把内存打爆。安装目录我一般用短路径比如C:\Qt不要带空格和中文。安装器对路径的兼容性比想象中差尤其是后续控制面板“更改”时旧路径里的特殊字符可能让维护模式找不到组件清单。安装过程中不要打开 Fiddler 的会话详情不要点开大响应预览让它安静跑完。安装完成后先别急着补组件打开 Qt Creator 新建一个空项目确认 Kit 能识别、能编译再进入下一轮。批次勾选内容目的观察点第 1 批Qt Creator 一个桌面 Kit先得到可编译环境安装器是否走完Fiddler 内存是否持续上涨第 2 批Sources补头文件、示例和源码索引请求数是否明显低于第一批第 3 批Debug Info 或附加模块按需补调试和扩展能力每轮只加一到两个大项4.2 控制面板“更改”补组件的顺序第一轮完成后打开 Windows 控制面板的程序列表找到 QT 的安装项选择“更改”。这个入口会重新拉起安装器维护模式已经装过的组件会显示为已选你只需要补勾新组件。每轮只加一到两个大项不要一次把 Sources、Debug Info、所有附加模块全勾上。补装顺序建议按依赖关系来先补 Sources再补调试信息最后补附加模块。Sources 的体积相对可控而且补完后 Qt Creator 的跳转和示例更完整调试信息通常更大放在后面单独一轮附加模块按项目需要来不用的不要勾。每轮补装前先确认 Fiddler 规则还在、证书还有效、会话列表已清空。补装过程中如果发现 Fiddler 内存快速上涨不要等它崩直接停止当前轮关掉安装器清空会话再重新打开维护模式。已经下载完成的组件不会因为中断全部丢失下一轮会从维护模式里继续。这个“中断再续”的操作比硬扛到 29% 闪退更省时间也更不容易把安装目录写坏。4.3 每轮安装后的磁盘与缓存检查每轮结束后做一次简单检查安装目录大小有没有异常增长、临时目录有没有残留大文件、Fiddler 进程内存有没有降下来。PowerShell 可以快速看目录大小# 查看安装目录总大小路径按你的实际安装目录替换 Get-ChildItem C:\Qt -Recurse -File | Measure-Object -Property Length -Sum | Select-Object Count, SumCount是文件数量Sum是总字节数。每轮补装后对比一次能看出这一轮实际落盘了多少。如果文件数量没怎么变、总大小也没变但安装器显示成功可能是组件被装到了别的目录或者维护模式没有真正写入。临时目录里的残留文件不要手动乱删尤其是安装器正在使用的缓存先关安装器再清 Fiddler 会话最后按安装器提示决定是否清理。磁盘空间不足时安装器可能在解压阶段失败表现却像下载失败所以每轮开始前看一眼剩余空间。4.4 一次成功率的估算与批次划分少量多次不是越碎越好。拆得太碎每轮都要重新走维护模式、重新校验时间成本会上去拆得太粗单轮请求数量又会上来。我的经验是分三到四批第一批最小可运行集第二批 Sources第三批调试信息第四批按需附加模块。每批之间重启一次 Fiddler清空会话确认上一批的组件在 Qt Creator 里可见。这样即使某一批失败也能定位到具体组件不会把前面已经成功的部分全部推倒重来。判断要不要再拆一批看两个信号Fiddler 会话列表在下载高峰期是否超过你机器的内存承受范围安装器进度是否长时间停在同一百分比。如果两个信号同时出现就把当前批再拆成两批如果只是网络慢但进度在走不要过度拆分。批次划分的目标是让每轮的内存峰值可控不是追求每轮只下一个文件。我的习惯是把最可能出问题的大组件单独放一轮其他小模块合并这样排查时目标最清晰。5. 避坑与排查29% 崩溃、内存被打满、规则不命中5.1 现象Fiddler 内存涨到几个 GB安装器在 29% 闪退现象很典型安装器进度停在 29% 附近Fiddler 进程内存一路涨任务管理器里看到几个 GB随后安装器无响应或直接退出。原因不是镜像站断了而是一次性勾选的组件太多Fiddler 会话列表保存了大量响应体和解码内容内存被抬到进程上限。解决顺序是先关安装器清空 Fiddler 会话关掉响应体预览再按第 4 章只勾最小集重跑后续用控制面板“更改”分批补组件。每轮开始前清会话不要点开大响应看内容这一条比换镜像更直接。5.2 现象规则写了但 Host 仍是官方主机规则贴进去后会话列表里的 Host 还是官方下载主机URL 也没有镜像前缀。优先查三处HTTPS 解密是否生效如果只看到CONNECT说明证书没被安装器信任规则是否写在OnBeforeRequest写在OnBeforeResponse不会改请求PathAndQuery是否真的以/online/开头有些请求路径可能不带这个前缀。解决方法是先在浏览器里验证镜像 URL再在规则里加FiddlerObject.log打印命中日志确认条件到底有没有进。不要靠猜日志比反复改规则快。5.3 现象镜像返回 404安装器重试后退出规则命中了Host 也变成了镜像站但响应码是 404。原因通常是路径前缀不对/qt/online/和/qtproject/online/混用或者镜像站同步延迟组件文件还没到位。解决方法是拿会话里的完整 URL在浏览器里分别替换两个前缀试返回 200 或 206 的那个才是可用前缀如果两个都 404换一个可达镜像站再验证。不要只看镜像首页能不能打开首页可达不代表组件目录存在。路径里的斜杠和大小写要逐字对少一个字符就是 404。5.4 现象控制面板找不到“更改”入口安装完成后想补组件控制面板里找不到 QT 的“更改”按钮。原因可能是安装器没有注册维护信息、安装目录被移动过、或者用绿色解压方式打开过安装器。解决方法是保留原安装器重新运行它进入维护模式如果维护模式也找不到检查安装目录是否完整必要时按最小集重装一次让注册信息恢复。不要直接删安装目录重来先确认安装器版本和安装路径没有变否则补装会变成全量重下。5.5 现象安装完成但 qmake 找不到或编译缺头文件装完 Qt Creator 和 Kit命令行里qmake找不到或者新建项目编译时报缺少头文件。原因通常是只装了 Kit 没装 Sources或者环境变量没有指向当前 Kit 的bin目录。解决方法是先在 Qt Creator 的 Kit 配置里确认编译器、Qt 版本、调试器三栏都有效再补装 Sources最后用绝对路径调用qmake -v验证版本。不要急着改系统环境变量Qt Creator 内部 Kit 能编译说明安装本身没问题命令行的路径可以后面再补。6. 验证与补装顺序三组命令确认最小安装真的能编译最小集装完后不要只看安装器显示“成功”要实际验证。第一组命令看qmake版本和路径第二组看编译器第三组编译一个空项目。命令行里执行# 第一组确认 qmake 指向你刚装的 QT 5.15.0 qmake -v where qmake # 第二组确认编译器可用MinGW 和 MSVC 按实际 Kit 替换 g --versionqmake -v会输出 QT 版本和安装路径版本必须是 5.15.0路径必须落在你刚才的安装目录下where qmake用来排查是不是命中了旧版本g --version只对 MinGW Kit 有意义MSVC 则用对应的开发者命令行验证。三组都通过后在 Qt Creator 里新建一个空窗口项目选刚装的 Kit 编译运行。能弹出窗口说明最小集是真的可用不是安装器“假成功”。补装顺序按第 4 章的批次走先 Sources再调试信息最后附加模块。每补一轮重复一次qmake -v和空项目编译确认新组件没有破坏原有 Kit。对比一次性全量安装分批补装的单轮会话数量更少Fiddler 内存峰值更低出问题时也更容易定位到具体组件。这个习惯我后来一直保留不管装哪版 QT先让最小集跑通再按需补不一次性勾满。方式单轮请求量内存峰值排查难度适用场景一次性全量高容易到顶高失败点难定位网络和机器都很宽裕最小集 分批补装低到中可控低每轮只验一个变量在线安装器容易闪退的环境这份 PDF 我一般放在手边当检查表先看规则段有没有把主机和路径前缀写对再看安装顺序有没有一次性勾满。需要原文档对照截图的人可以在资料页拿这份 PDF拿到后先翻规则段把镜像主机和路径前缀换成你用浏览器验证过的地址再按最小集走第一轮。从那以后我每次装 QT 5.15.0 都先把最小集跑通再按批次补组件不一次性勾满希望帮到你。本文还有配套的精品资源点击获取
阅读完成 · 觉得有帮助？
