简介QT 5.15.0 自发布后改为在线安装方式不少开发者因官方下载缓慢、安装程序中途崩溃而受阻。这份原创 PDF 针对该痛点完整记录了以 Fiddler 4 代理配合清华、北外、华中等国内镜像的实测方案并重点解决了数据量过大导致安装失败的问题适合需要在网络受限环境中安装 Qt 的 C/嵌入式开发者参考。资源为单一 PDF 文件压缩包大小仅 833KB内容精炼包含问题描述、原因分析、代理规则配置及分步截图可直接按图操作。目前已有 12100 人学习下载验证了其实用性。通过学习可掌握镜像站点改写规则、先装核心模块再在控制面板中增量添加组件的思路有效避开官网直连不稳定的坑大幅提升 5.15.0 在线安装成功率。1. 在线安装 QT 5.15.0 卡在哪一个安装器、一个账号、一个 Archive 开关QT 5.15.0 是我这几年用得最多也最折腾的一个 Qt 版本。折腾的不是编译本身而是它的在线安装安装器打开先要登录账号登录完默认列表里又看不到 5.15.0找到之后下载速度还可能让人血压升高。如果你也是被 qt-unified-windows-x64-online.exe 这个在线安装器卡住的开发者这篇笔记就是给你准备的账号、Archive 开关、镜像源参数、工具链选择每一步都按我实际验证过的路径写照着点就能把 5.15.0 装进指定目录。全文不碰任何绿色版、精简版方案就用官方安装器把它“驯服”。“在线安装”这四个字坑点都在“在线”上安装器本身只是个壳子真正的 Qt 库、工具链、Creator 全部要从远程仓库现场拉取。这意味着账号状态、仓库地址、版本筛选、磁盘缓存任何一个环节出问题安装都会卡在半路。这篇笔记按安装顺序把最关键的四个节点讲透读完你会理解为什么“双击下一步”在 5.15.0 上行不通以及怎么改才能真正稳定。2. 从下载安装器到看见 5.15.0账号关键点与 Archive 的正确勾法2.1 在线安装器文件与三种启动方式Qt 5.15.0 不像 5.9、5.12 时代那样随手能找到一个大而全的离线安装包官方把安装逻辑收敛成了一个小体积的在线安装器。Windows 上最常见的文件名是 qt-unified-windows-x64-online.exe体积通常只有几十 MB。它本身不携带 Qt 组件包而是维护一个指向远程仓库的下载列表你选中组件后现场下载并解压这就解释了为什么安装过程对网络状态这么敏感。除了双击运行我更推荐一开始就用命令行方式启动在线安装器。原因很简单安装器的很多关键配置只能在命令行参数里指定纯界面操作根本看不到这些选项。下面这条命令是我在干净环境里验证过的最小区块qt-unified-windows-x64-online.exe --accept-licenses --accept-obligations --default-answer--accept-licenses表示预先同意许可证条款界面里不会再反复弹协议提示--accept-obligations是同意开源或商业协议下的义务说明比如开源版需要确认“仅按开源协议使用”--default-answer是在安装器抛出询问时默认选“是/接受”。三个参数组合起来能省掉至少十次弹窗点击。对于只想看流程的读者双击安装器也能走完但后面配置镜像源时铁定要回到命令行这是 Qt 安装框架的固有设计早用早省事。2.2 账号登录网页能进、安装器进不去的三个细节5.15.0 的在线安装器强制要求登录 Qt 账号这一步拦住的人比后续所有步骤加起来都多。我见过一位同事在网页端反复确认账号密码没问题安装器里却一直提示无效凭证折腾了两小时。仔细排查下来问题基本集中在三个点。第一安装器登录框对密码里的特殊字符很敏感。如果密码里含 、%、 这类字符建议临时改成纯字母加数字的组合登录装完再改回高强度密码。第二输入法状态会导致密码串进全角字符登录失败的表现是“瞬间报错而不是等待验证”。第三账号要提前在 Qt 官方网站注册并且邮箱要完成验证没验证的邮箱账号在网页端浏览没问题在安装器里多半会被拒绝。账号登录成功后安装器会进入欢迎向导里面有一项是选择“开源版”还是“商业评估版”。根据实际用途选开源开发选 Qt 开源版后续协议确认选同意即可。如果选错成商业评估版组件列表和开源版基本一致但许可证状态会在企业内网部署时埋下合规隐患建议一开始就选对。2.3 Archive 开关为什么 5.15.0 藏在“旧版本”里账号通过之后大多数人会卡在“组件列表里找不到 5.15.0”。这不是你眼花了而是 Qt 官方维护策略导致的。从 5.15 开始官方在线安装器默认只展示“当前受支持的版本”5.15.0 这种不再有免费补丁支持的版本被归类到 Archive 分类里默认不显示。解决办法是勾选安装器组件列表下方的 Archive 或“存档”复选框。这个开关不在明显位置而在版本列表的过滤器区域需要往下翻或者点开“版本”下拉菜单。勾选后列表里会出现 5.15.x 整条线5.15.0、5.15.1、5.15.2……一直排到这条线的最后一个版本你就能看到 5.15.0 了。注意一个细节Archive 开关勾选后组件列表会变长很多因为所有历史版本都被拉出来了。这时候用列表右上角的筛选框直接输入 5.15.0可以精确定位。还有个容易翻车的点如果你用的是镜像源而镜像源没有同步 archive 目录那么勾选 Archive 后依然看不到版本。这个钩子问题在第三章专门讲你先记住“Archive 是否可见取决于仓库目录里有没有 archive”这个结论。2.4 选完组件之后的下载环节别急着关窗口组件勾选完成、点击“下一步”之后安装器会进入下载阶段。很多人以为这一步就是纯等待实际上它是整个安装里最脆弱的一环在线安装器会逐包下载、校验哈希、解压到安装目录。中途关窗口、断网、磁盘空间不足都会让安装停在半路而且重启安装器后它不会总是自动续传可能卡在同一个包上反复失败。我把这一步单独拎出来说是因为它直接决定了你要不要看下一章。如果你的下载速度正常、二十分钟内跑完那恭喜你如果看到进度条长时间不动或者某个包反复下载失败千万别反复重试直接去配镜像源。在进入镜像源配置前先记住一个缓存概念安装器会把下载的临时包放在用户目录的 Qt 缓存目录里下文排错环节还会用到它。3. 下载速度和失败率都靠它--mirror 镜像源参数的正确接法3.1 安装器下载包的机制先理解远程仓库结构在线安装器从界面看是“点下一步等进度条”底层逻辑是拉取一个远程 Qt 仓库的索引再按索引逐个下载组件包。因此决定下载快慢和成败的核心不是你的网络带宽而是安装器连接的远程仓库地址。默认仓库地址指向 Qt 官方服务器节点从某些网络环境访问时延迟高、连接不稳定这就是“下载慢到怀疑人生”的根因也是“网络玄学”这个词在 Qt 安装圈子里流传开来的原因。理解了这一点解决方案就清楚了给安装器换一个远程仓库地址。Qt 安装框架原生支持这个操作参数就是--mirror。这不是什么 hack而是官方提供的接口不少镜像站都是靠这个参数为开发者提供高速下载的。知道这个参数的人很多但用错的人更多最常见的问题有三个镜像地址格式不对、末尾漏了/qt、镜像站本身没有完整同步 Qt 仓库导致选完组件后一堆包 404。3.2 最小可行的镜像启动命令先看一条完整可用的命令再做逐项说明qt-unified-windows-x64-online.exe --mirror https://mirrors.example.cn/qt --accept-licenses --accept-obligations --default-answer把https://mirrors.example.cn/qt替换成你确认可用的镜像仓库地址。注意地址必须以/qt结尾因为镜像站通常同时同步了多个软件仓库Qt 内容单独放在qt子目录下。安装器会从这个地址读取仓库索引之后所有组件包都从这个域名下载。--mirror参数的值和官方服务器结构一致安装器内部会在镜像地址后面追加online/qtsdkrepository之类路径去拼完整仓库 URL。如果你在镜像站首页能看到“Qt 在线仓库”并且提供了/qt/online/qtsdkrepository的目录结构说明这个地址可以直接用。参数位置没有强制要求但建议放在第一个参数位避免被其他参数解析干扰。3.3 怎么验证镜像源是否可用三步检测法镜像源不可用的坑比官方服务器慢还要折磨人因为报错信息不够直白。我一般用三步定位一个镜像地址能不能用。第一步在浏览器里直接打开镜像根目录确认目录列表里存在qt/online/qtsdkrepository路径。如果没有这个路径说明该镜像没有同步 Qt 在线仓库直接换一家。第二步点进qtsdkrepository查找是否存在windows_x86或windows_x86_64子目录找不到说明同步不完整装到一半必然失败。第三步把镜像地址复制进安装器如果安装器在读取仓库索引时报“无法解析仓库”或直接回退到默认服务器检查是不是用了 http 而镜像只支持 https或者反过来。这一套检测做完基本能排除大多数镜像源问题。顺带说一句镜像源是否显示 5.15.0取决于镜像同步策略是否包含 archive 目录。有些镜像为了省空间只同步最新版Archive 列表就是空的这正好解释了上一章末尾说的“勾了 Archive 也看不到 5.15.0”。3.4 镜像参数与账号、协议参数的组合场景实际安装时很少有人只带一个--mirror参数跑完流程因为缺少账号参数会强制弹登录框缺少协议参数会到处让点“下一步”。我常用的组合如下qt-unified-windows-x64-online.exe --mirror https://mirrors.example.cn/qt --accept-licenses --accept-obligations --default-answer --email yourexample.com --pw yourpassword--email和--pw用于提前传入账号信息避免登录框交互。这里有两个使用习惯要提醒一是命令行里明文带密码进程列表会短暂暴露密码个人机器可用共用机器不建议二是密码里带特殊字符时准备一个不带特殊字符的临时密码。这个组合装完 Qt 5.15.0 之后MaintenanceTool 也会沿用同一套镜像配置后续增删组件直接双击就能用不会再次掉回官方慢速源。4. 组件勾选与工具链匹配MinGW 该勾还是 MSVC 该勾4.1 工具链三选一看懂 5.15.0 组件列表里的编译器名Qt 5.15.0 的组件列表里Qt 5.15.0 这一大项下会细分出多个子项命名大概长这样MinGW 8.1.0 32-bit、MSVC 2019 32-bit、MSVC 2019 64-bit 等等。这些子项同时包含两样东西针对该编译器的 Qt 预编译库以及对应的编译器工具链。MinGW 自带工具链MSVC 则需要外挂微软的编译环境。这个命名误导过不少人。有人勾了 MSVC 2019 64-bit 就以为微软编译器也一起装好了实际上 Qt 安装器并不打包 MSVC 编译器本体它只提供与 MSVC ABI 兼容的 Qt 库。如果你没装 Visual Studio 或对应的 Build Tools编译时就会报“找不到 cl.exe”。反过来MinGW 子项中的编译器是随 Qt 一起装进安装目录的路径一般在 Qt 安装目录下的Tools\mingw810_64\bin换句话说选 MinGW 等于一揽子解决 Qt 库和编译器。我做选择的标准很简单如果项目最终要交付给第三方且第三方环境可能没有 Visual Studio选 MinGW如果项目要对接 Windows SDK、驱动或大量使用 MSVC 独有的编译宏选 MSVC然后老老实实先装好对应版本的 Visual Studio Build Tools。这里不存在谁更优只有谁和你现有的交付环境更匹配。4.2 按工作场景取舍勾选组件搞清楚哪些该勾哪些别动组件列表第一次打开时默认勾选的是 qtbase 全家桶和 Qt Creator、Qt 调试工具等基础项。真正的体积大头在附加模块里。下面这张表是我在 5.15.0 上的常用取舍按场景推荐组件默认状态使用场景我的建议Qt 5.15.0 (qtbase)已勾选核心库必须保持勾选Qt Charts未勾选曲线、统计图图表项目必勾Qt Data Visualization未勾选3D 数据展示按需体积较大Qt WebEngine未勾选内嵌浏览器页面体积最大的模块谨慎Qt Sources未勾选调试时看源码建议勾选Qt Debug Information Files已勾选崩溃栈解析磁盘够就保留附加 Qt 版本线未勾选多版本对比不需要别勾磁盘翻倍Android 相关未勾选移动端开发不做 Android 不勾这套取舍的核心思想是“按项目勾不要全选”。我见过有人为了省事把 5.15.0 下所有子项全勾上装完磁盘少了 30 多 G其中一大半是 WebEngine 和 Android 工具链而这些组件在后续桌面项目里根本不会用到。勾了两个线版本之后磁盘体积不是线性增长因为每条版本线都包含完整工具链代价比你想的高。4.3 安装目录与杀软拦截两个容易被忽略的路径坑安装路径这一项界面默认给的是一个带空格和用户名的路径。我强烈建议改成纯英文、无空格的路径比如D:\Qt\5.15.0。原因有两个一是部分工具链脚本对路径空格处理不够健壮装完编译时冒出莫名其妙的 file not found你得花半小时才能确认是路径问题二是后续如果你要把 Qt 目录整体打包给同事或放进 CI 环境带空格路径会多出一堆转义麻烦。另一个常被忽略的坑是杀毒软件。安装器会释放大量可执行文件和编译器工具链某些行为拦截策略会把mingw32-make.exe或qmake.exe当成风险程序隔离。表现是安装过程报错或者装完再启动 Qt Creator 提示找不到 qmake。遇到这种情况把 Qt 安装目录加入杀软信任名单然后重新执行安装器检查组件完整性而不是重装整个 Qt重装解决不了信任问题。4.4 源码包和调试符号建议勾但不一定装在哪最后说两个容易后悔的选项。Qt Sources默认不勾但我建议勾上因为调试时按 F11 跳进 Qt 内部源码非常方便C 开发者应该都懂黑匣子状态下排错的痛苦。Qt Debug Information Files会为每个库生成调试符号体积不小但对崩溃日志的定位价值很大。这两项都不影响安装成败只影响事后排错效率。如果磁盘紧张可以优先保 Qt Sources放弃调试符号文件。因为符号文件在没有专用符号服务器时用处有限而源码是随时能翻的。这个取舍我踩过坑一开始图省事两个都没勾后来项目在 QTreeView 里出现诡异重绘问题只能对着汇编猜逻辑白白折腾一个晚上。5. 在线安装失败排查五个高频坑的现象、原因、解决5.1 现象登录界面转圈后提示登录失败现象是安装器里账号密码输完界面长时间转圈最后弹“登录失败”但同一个账号在网页端能正常登录、也能看到开源协议确认页。排查时先看密码里有没有特殊字符再检查输入法是否被切成中文全角。原因多半是密码字符引起本地解析异常或者本地缓存里存了之前的会话凭证。解决方案是到用户目录下删除 Qt 安装框架的缓存会话文件%LOCALAPPDATA%\Qt下的相关子目录删掉重新启动安装器重新登录。这个目录还会保存下载缓存一并清掉也不亏反正后面要重下。5.2 现象下载到某个包一直卡住重试仍失败现象是进度条走到某个百分比后长时间不动网络看起来正常重启安装器后进度回退反复在同一位置失败。原因是安装器把下载包的临时数据写进了本地缓存缓存文件受损后安装器不会自动重新下载而是反复尝试续传一个坏文件。解决方法是彻底退出安装器删除%LOCALAPPDATA%\Qt缓存目录再带--mirror镜像参数重新安装。这是我踩过最深的一个坑傻乎乎点重试按钮点了十几次进度条每次都在同一个文件上停下最后清掉缓存才恢复正常属于典型的血泪经验。5.3 现象勾选 Archive 后仍然看不到 5.15.0现象是已经打开 Archive 开关版本列表里只有 5.15.2 或更新的版本没有 5.15.0。原因和第三章强调的一致安装器展示的版本列表来自远程仓库索引镜像源如果不同步 archive 目录5.15.0 就永远不会出现。解决方法是换一个同步完整的镜像源换完再打开 Archive 开关重新拉取仓库索引。验证镜像是否包含 archive 目录的方法回到前文的三步检测法浏览器直接看目录列表比在安装器里瞎等高效得多。5.4 现象装了 MSVC 库但编译找不到 cl.exe现象是安装时勾选了 MSVC 2019 64-bit 组件安装完成后新建项目编译控制台报 cannot find cl.exe 或类似错误。原因是 Qt 安装器只装了 Qt 库没装也不会装微软编译器你的机器上根本没有 MSVC 工具链。解决方法是先安装对应版本的 Visual Studio Build Tools并在安装时勾选“使用 C 的桌面开发”工作负载确保 cl.exe、mt.exe 等工具就位。装完后建议用 x64 Native Tools Command Prompt 打开 Qt Creator让环境变量正确传递否则即使装了工具链Creator 也可能探测不到。5.5 现象Qt Creator 套件页黄色感叹号现象是 Qt Creator 打开后左侧套件页面看到编译器列显示未设置或黄色感叹号项目无法构建。原因大多是安装完成后 Creator 自动探测失败常见于自定义安装目录或非默认的 MinGW 版本。解决方法是手动在“工具→选项→套件”里指定编译器路径MinGW 编译器在 Qt 安装目录的Tools\mingw810_64\bin\g.exe调试器在同一个 bin 目录下的gdb.exeqmake 在对应的5.15.0\mingw81_64\bin\qmake.exe。路径填对后套件状态会立刻变绿重新打开项目即可。这里面还有个细节64 位 Qt 配 32 位编译器也会提示不匹配套件架构要和库架构一致。6. 装完不能只“看到图标”验证工具链与无人值守安装的参数组合6.1 第一次编译的验证三步装完之后我习惯用一个小例子验证“库和编译器真的通了”而不是急着打开 Creator 建大项目。新建一个目录写一个最小程序#include QCoreApplication #include QDebug int main(int argc, char *argv[]) { QCoreApplication app(argc, argv); qInfo() Qt version: QT_VERSION_STR; qInfo() Qt is ready.; return app.exec(); }然后在这个目录下用命令行完成编译qmake -project qmake mingw32-make第一条命令生成工程文件第二条根据 qmake 配置生成 Makefile第三条调用编译器把 main.cpp 编成可执行文件。用 MinGW 工具链时编译命令是 mingw32-make而不是 make。如果这三步都过并且运行生成的程序在控制台打印出 Qt 版本号说明 Qt 库、编译器、qmake 的路径三者已经对齐后续在 Creator 里建项目基本不会再出环境问题。这一步能过滤掉九成“装完不能编译”的隐性故障。6.2 无人值守安装的组合参数验证过后如果要在第二台机器或 CI 环境重复安装就可以把整条命令固化下来qt-unified-windows-x64-online.exe --mirror https://mirrors.example.cn/qt --accept-licenses --accept-obligations --default-answer --email yourexample.com --pw yourpassword --root D:\Qt--root指定安装根目录--mirror指定镜像源配合协议接受参数后安装器几乎不会弹出交互框。共用机器上不要明文存密码可以用环境变量先导出再在命令里替换占位符。这条命令最重要的价值是可复现同一个参数组合在不同机器上的安装结果一致排错时也好沟通不用反复问对方“你刚才点的是哪一步”。6.3 MaintenanceTool后续加减组件的入口安装完成后Qt 安装目录下会有一个 MaintenanceTool.exe它和在线安装器是同一个东西只是跑在维护模式下。用它加减组件时一样要把--mirror参数带上否则它会尝试连官方默认源速度回到原点。这也是我强调镜像参数要写进维护工具的原因装完只是开始后面加一个 Qt Charts、补一个调试符号包都需要走这条路径。用 Qt 5.15.0 这两年我最大的教训是在线安装问题九成不是 Qt 的问题而是没有把账号、镜像源、Archive、工具链这四个变量一次性对齐。第一次失败就怀疑安装包损坏、甚至想换绿色版其实低估了官方安装器本身的可控性。先按这篇笔记的顺序排查一遍大部分问题在十分钟内都能定位到具体环节。希望帮到你。本文还有配套的精品资源点击获取