macOS安装Qt5.12.0后Qt Assistant为空找不到qch文件怎么办

问题复现场景 #

• 运行环境：macOS Catalina 10.15.6
• 安装版本：Qt 5.12.0
• 异常表现：启动Qt Assistant后界面无任何内容，本地全局搜索.qch格式帮助文档无匹配结果，常规检索找不到对应版本的qch文件有效下载源。
  

修复步骤 #

• 找到Qt安装根目录下的MaintenanceTool可执行文件，双击启动后选择添加或移除组件选项，进入组件勾选页面。
• 在组件树中展开已安装的Qt 5.12.0版本节点，找到子项Qt Documentation（Qt文档），勾选该组件后点击下一步执行安装，工具会自动下载匹配当前Qt版本的全套.qch格式官方文档。
• 安装完成后重启Qt Assistant即可正常加载文档。如果重启后仍为空白，打开菜单栏路径 编辑 -> 偏好设置 -> 文档，手动选中Qt安装目录下Docs/Qt-5.12.0文件夹内的所有.qch文件添加到文档列表，确认后重启工具即可。
• 如果启动维护工具时提示官方源连接失败，可先在维护工具的设置-临时源页面添加国内Qt镜像地址，更新源缓存后再执行文档组件安装即可。

避坑提示：不要下载第三方站点分享的零散.qch文件，版本不匹配会出现文档索引错乱、代码示例缺失、内部链接跳转失败的问题，通过Qt官方维护工具安装对应版本的文档组件是最稳定的方案。

内容的提问来源于stack exchange，提问作者CN_Cabbage