Qt5.15.2离线安装时提示“无法连接到在线存储库”如何解决？

Question

**问题：Qt 5.15.2 离线安装时提示“无法连接到在线存储库”如何解决？** 该错误常见于离线环境下运行官方在线安装程序（qt-unified-windows-x64-4.x.exe）时，即使已下载离线包，安装器仍默认尝试联网校验或加载远程元数据。根本原因在于安装器未正确识别离线模式，或本地存储库路径配置缺失/无效。典型表现包括卡在初始化界面、报错“Failed to connect to repository”或自动跳转至网络超时。注意：Qt 5.15.2 官方不再提供纯离线安装包（.exe 或 .7z），其“离线安装”实为预下载的本地镜像+离线安装器组合，需严格匹配版本与架构，并通过命令行强制启用离线模式（如 `--offline` 参数）。若忽略此步骤，安装器将强行回退至在线模式，导致失败。此外，防火墙、代理残留、hosts 文件劫持或 Qt Account 登录状态异常也可能触发误判。解决方案需从安装器调用方式、本地源配置及环境隔离三方面协同处理。

Answer 1

```html

一、现象层：识别典型错误表现与上下文边界

当在无网络环境（如内网开发机、军工涉密终端、CI 构建沙箱）中双击 qt-unified-windows-x64-4.4.2.exe（对应 Qt 5.15.2）时，安装器卡在“Initializing”或弹出红色提示：“Failed to connect to repository”，日志中高频出现 QNetworkReply::NetworkError::ConnectionRefusedError 或超时（TimeoutException）。注意：此非 Qt SDK 本身编译错误，而是 Unified Installer（Qt Online Installer v4.x）的元数据加载失败——它默认以“在线优先”策略启动，即使你已下载完整离线镜像（如 qt5_5152_offline.7z）。

二、机制层：深入 Unified Installer 的离线判定逻辑

• Installer 启动时会按序检查：--offline 参数 → 环境变量 QT_OFFLINE_INSTALLER=1 → 配置文件 installer.cfg 中 [General]/offline=true → 最终 fallback 到在线模式
• 本地存储库必须满足严格路径结构：<mirror-root>/online_repository/Updates.xml（由 repogen 工具生成），且 Updates.xml 的 <Repository> 节点需包含完整组件哈希与路径映射
• Qt Account 登录状态会触发隐式网络心跳（即使未登录，Installer 仍会尝试访问 https://account.qt.io 校验 token 缓存）

三、诊断层：系统化排查清单（含验证命令）

检查项	验证方法	预期结果
离线参数是否生效	qt-unified-windows-x64-4.4.2.exe --offline --dir C:\Qt --no-opengl-sw	启动后控制台输出 Offline mode enabled
本地仓库完整性	dir /s C:\QtMirror\online_repository\*.xml	必须存在 Updates.xml 和 Updates.xml.sha1
hosts 文件劫持	findstr "qt.io account.qt.io" %windir%\System32\drivers\etc\hosts	返回空行（无重定向条目）

四、解决层：三阶段强制离线部署方案

1. 阶段一：环境净化
   关闭 Windows 代理（设置 → 网络 → 代理 → 关闭“使用代理服务器”）；清空 %LOCALAPPDATA%\QtProject\QtInstallerFramework\ 下所有缓存；删除 %APPDATA%\QtProject\QtAccount\ 目录
2. 阶段二：镜像预配
   使用官方 Qt Installer Framework 4.4.2 解压离线包至 C:\QtMirror，确保其包含 online_repository 子目录及有效 Updates.xml
3. 阶段三：原子化安装
   以管理员权限执行：
   qt-unified-windows-x64-4.4.2.exe --offline --mirror C:\QtMirror --dir C:\Qt5152 --no-opengl-sw --script install.qs（其中 install.qs 为预定义静默脚本）

五、进阶层：构建可复用的离线 CI 流水线（Mermaid 流程图）

flowchart TD
    A[下载 qt5_5152_offline.7z] --> B[解压至 C:/QtMirror]
    B --> C[运行 repogen -p C:/QtMirror -r C:/QtMirror/online_repository]
    C --> D[生成校验文件 Updates.xml.sha1]
    D --> E[打包为 ISO 或 WIM 镜像]
    E --> F[CI Agent 挂载镜像]
    F --> G[执行 --offline --mirror 命令]
    G --> H[验证 C:/Qt5152/5.15.2/msvc2019_64/bin/qmake.exe -v]

六、避坑层：高危操作红区警示

• ❌ 不要双击安装器图形界面启动——GUI 模式会忽略 --offline 参数（仅命令行生效）
• ❌ 不要混用不同版本镜像（如 Qt 5.15.2 镜像 + Qt 6.5 安装器），会导致 Component checksum mismatch
• ❌ 不要将镜像放在 OneDrive/Google Drive 同步目录下，NTFS 符号链接可能被云服务破坏
• ✅ 推荐在安装前执行：set QT_DEBUG_PLUGINS=1 && set QT_LOGGING_RULES="qt.network.ssl.warning=false" 屏蔽 SSL 证书误报

七、验证层：离线完备性黄金指标

成功安装后，必须通过以下四重验证：

1. 运行 C:\Qt5152\5.15.2\msvc2019_64\bin\qmake.exe -v 输出包含 Using Qt version 5.15.2
2. 打开 Qt Creator → Tools → Options → Kits → Compilers，确认 MSVC 2019 编译器自动识别
3. 新建 Qt Widgets Application 项目，点击 Build 无 network unreachable 错误
4. 执行 netstat -ano | findstr :443 返回空——证明无任何后台连接尝试

```