公众号：cpp手艺人
QWebEngine 安装、环境准备与版本选择策略
QWebEngine 是 Qt 基于 Chromium 的 Web 渲染模块，被广泛用于桌面应用中的内嵌浏览器、Hybrid 页面渲染、WebGL 场景以及 Web 应用容器。
但第一次使用时，很多开发者会遇到以下问题：
- QWebEngine 要如何安装？
- 需要准备哪些开发环境？
- Qt 版本怎么选？WebEngine 和 Chromium 有什么关系？
- 不同平台需要注意哪些坑？
本指南将从安装、环境准备、版本选择到验证方式，给你一套完整清晰的落地方案。
1. QWebEngine 安装方式总览
QWebEngine 不作为独立库发布，它始终和Qt 版本绑定。
最常见的三种安装方式：
- Qt 官方 Online Installer（推荐）
- 源码编译 Qt（高阶）
- Linux 发行版提供的预构建包（运行环境）
开发环境优先使用Qt Installer；运行环境可使用系统包管理器。
2. 各平台的安装步骤
2.1 Windows 安装
步骤 ①：下载 Qt Installer
从 Qt 官网下载 Online Installer。
步骤 ②：选择组件
在安装界面勾选：
- Qt（如 5.15.2 / 6.5 / 6.6 / 6.7）
- Qt WebEngine
- MSVC 或 MinGW 编译器（推荐 MSVC）
- Qt Creator（可选）
步骤 ③：编译器选择建议
| 编译器 | 推荐度 | 说明 |
|---|---|---|
| MSVC（2019 / 2022） | ⭐⭐⭐⭐⭐ | 官方最佳兼容性 |
| MinGW | ⭐⭐ | Qt6 开始兼容性下降，部分版本缺失 WebEngine |
强烈建议使用 MSVC，否则可能遇到 WebEngine 模块不存在的问题。
2.2 macOS 安装
macOS 下安装与 Windows 类似：
- Qt Installer
- 勾选 Qt WebEngine
- 使用系统自带的 Clang 编译器
无需额外安装 MSVC 或 MinGW。
2.3 Linux 安装
Linux 提供三种方式：
✔ 方式 1：Qt Installer（开发环境）
跨发行版，版本统一，最稳定。
✔ 方式 2：系统包管理器（运行环境）
例如：
sudo apt install qtwebengine5-dev但版本可能较旧，受发行版影响较大。
✔ 方式 3：源码编译 Qt（高阶）
可用于定制 Qt 或 Chromium 但编译耗时巨大（2～5 小时）。
3. 如何验证 QWebEngine 是否安装成功？
3.1 方法 1：运行 Qt 示例
Qt Creator → Welcome → Examples → WebEngine →Simple Browser
运行如果能正常加载网页 → 安装成功。
4. 版本选择策略（核心部分）
4.1 最重要的一条规则
QWebEngine 必须随 Qt 版本走，不能单独升级。
因为 Qt 需要为不同版本的 Chromium 做适配。 强行升级会导致：
- 无法编译
- 渲染黑屏
- WebGL 崩溃
- 视频无法播放
| Qt 版本 | Chromium 内核 | 特性 |
|---|---|---|
| Qt 5.12 | 69 | 较旧 |
| Qt 5.15 | 87 | 最稳定 |
| Qt 6.2 | 90 | 现代化特性 |
| Qt 6.5（LTS） | 108 | 推荐 |
| Qt 6.6 / 6.7 | 110+ | 功能更新 |
4.2 不同项目的推荐版本
✔ 企业级：稳定第一
- Qt 5.15.2 LTS
- Qt 6.5 LTS
✔ 对 Web 新技术要求高（WebGPU / WASM）
- Qt 6.6 / 6.7 / 6.8
✔ 游戏、WebGL、大型渲染应用
- Qt ≥ 6.2
✔ 不求新但求稳定
- 永远选 Qt 5.15.2 或 Qt 6.5 LTS
5. 最佳实践总结
| 场景 | 推荐解决方案 |
|---|---|
| 普通商业软件 | Qt6.5 LTS |
| 长期维护项目 | Qt6.5 LTS |
| 使用 3D / WebGL / WASM | Qt6.6+ |
| 稳定优先的项目 | Qt5.15.2 LTS |
| 不确定怎么选 | Qt 6.5 LTS |
