Qt WebEngine 平台笔记#

包含关于 Qt WebEngine 模块特定问题的信息。

从源码构建 Qt WebEngine#

不支持静态构建。

每个支持的平台都单独列出了构建 Qt 模块所需的源码要求

  • Qt for Windows - 从源码构建

  • Qt for X11 要求

  • Qt for macOS - 从源码构建

此外，构建 Qt WebEngine 模块还需要以下工具

所有平台#

在所有平台上，构建时需要以下工具

  • C++20 编译器支持

  • CMake 3.19 或更新版本

  • Python 3 配置 html5lib 库

  • Bison, Flex

  • GPerf

  • Node.js 版本 14 或更高

Windows#

在 Windows 上，还需要以下额外工具

  • Visual Studio 2019 或更高，或 clang-cl 版本 10 或更高

  • 活动模板库（ATL），通常包含在 Visual Studio 安装中

  • Windows 11 SDK 10.0.22621.0 或更高版本

注意

不建议使用来自 msys2 或 cygwin 的工具来构建 Qt WebEngine，因为它可能会导致构建错误。

Linux#

在 Linux 上，需要 Clang 或 GCC 版本 9 或更高。

Qt WebEngine 需要 pkg-config 来检测大多数其依赖项。需要以下 pkg-config 文件

  • dbus-1

  • fontconfig

如果 Qt 配置了 xcb，还需要以下 pkg-config 文件

  • libdrm

  • xcomposite

  • xcursor

  • xi

  • xrandr

  • xscrnsaver

  • xtst

macOS#

在 macOS 上，需要以下内容

  • macOS 10.14 或更高

  • Xcode 12.0 或更高

  • macOS 11 SDK 或更高

注意

Qt WebEngine 无法为 macOS 的 32 位模式构建（使用 macx-clang-32 mkspec）。

使用较早的 Qt 版本构建 Qt WebEngine#

支持使用较旧的 Qt 版本（直到最后一个 LTS 版本）构建 Qt WebEngine。这意味着 Qt WebEngine 6.4 可以用 Qt 6.2.x、Qt 6.3.x 和 Qt 6.4 构建于。

要使用较旧的 Qt 版本构建 Qt Webengine

  1. 下载 qtwebengine 源代码。

  2. 从较早的 Qt 版本，运行 qmake && make (&& make install)。

Mac App Store 兼容性#

使用 Qt WebEngine 的应用程序与 Mac App Store 不兼容，因为这些原因：

  • 代码中的 Chromium 部分使用了几个私有的 API 方法，这些方法在 App Store 中是被禁止的。

  • 提交给 App Store 的应用程序必须进行带 App Sandbox 功能的代码签名。App Sandbox 功能会干扰 Chromium 自己的沙盒初始化，导致 Chromium 无法正常初始化。这也与私有 API 的使用有关。此外，即使工作是为了绕过 App Store 的限制，这也不能保证库的正确行为。

在双显卡 MacBook 上的 macOS Airplay 支持#

为了使 Qt WebEngine 在从支持 GPU 切换的 MacBook 流式传输到 AppleTV 时能够正常工作，重要的一点是向应用程序的 Info.plist 文件中添加 NSSupportsAutomaticGraphicsSwitching 选项，并将其值设置为 YES。否则，在切换 Airplay 开启或关闭后创建新的网络引擎视图实例时可能会出现渲染问题。

默认 QSurfaceFormat OpenGL 配置文件支持#

如果必须设置一个具有改动后的 OpenGL 配置文件的新默认 QSurfaceFormat，应在应用程序实例声明之前设置它，以确保所有创建的 OpenGL 环境都使用相同的 OpenGL 配置文件。

在 macOS 上，如果应用程序实例后设置默认 QSurfaceFormat，则应用程序将以 qFatal() 退出，并打印一条信息，指出默认 QSurfaceFormat 应在应用程序实例之前设置。

沙盒支持#

Qt WebEngine 为 Chromium 渲染进程提供即用型沙盒支持。

在 Linux 上请注意以下限制

  • 内核必须支持匿名命名空间功能（内核版本 3.8 或更高）。然而，在 Debian、Ubuntu 和其他基于 Debian 的发行版中，此功能默认关闭。可以通过将 /proc/sys/kernel/unprivileged_userns_clone 设置为 1 来启用它。

  • 内核必须支持 seccomp-bpf 功能（内核版本 3.5 或更高）。

  • 不支持 setuid 沙盒，因此已被禁用。

要显式禁用沙盒，请使用以下选项之一

  • 将 QTWEBENGINE_DISABLE_SANDBOX 环境变量设置为 1。

  • 向用户应用程序可执行文件的命令行参数传递 --no-sandbox。

  • 将 QTWEBENGINE_CHROMIUM_FLAGS 设置为 --no-sandbox。

有关更多信息，请参阅 使用命令行参数 。

Docker 环境中的内存要求#

当在 Docker 容器中运行 Qt Web Engine 示例并浏览内容丰富的网站时，可能会报告 BUS 错误（SIGBUS）。通常这由 Docker 在一个内存空间太小（如 64MB）的容器中运行引起。为了修复此问题，请增加内存空间大小。

可访问性和性能#

Qt WebEngine 在满足以下条件时启用对网页的支持

  • Qt Core 配置并使用带有可访问性支持的构建。

  • 操作系告诉 QPA 插件激活可访问性。例如，当在 Windows 上使用屏幕阅读器应用程序或在 macOS 上使用 VoiceOver 时。

在某些旧的 Linux 配置中，可访问性可能会导致大型 HTML 页面的显著减速。

因此，可以通过将 QTWEBENGINE_ENABLE_LINUX_ACCESSIBILITY 环境变量设置为 0 来在 Linux 上禁用 Qt WebEngine 的辅助功能支持。

Windows全屏应用程序中的弹出窗口#

由于 Windows 合成器的限制，显示全屏 Web 引擎视图的应用程序将无法正确显示弹出窗口或其他顶级窗口。原因和解决方案请参见“基于 OpenGL 的全屏窗口”。

Windows应用程序清单#

清单是一个在程序启动时读取的 XML 文件，用于通知 Windows 如何运行程序。某些 Qt WebEngine 功能可能需要在 Windows 上正确运行的用 户应用程序中添加清单文件。

以下代码示例展示了清单文件的结构及其如何嵌入到程序中。

注意

这些代码示例来自 WebEngine Quick Nano 浏览器示例。

清单文件定义了应用程序支持的 Windows 版本。httpUserAgent 需要此信息来报告正确的 Windows 版本。

<Code snippet "/data/qt5-full-670/6.7.0/Src/qtbase/../../../../examples/webenginequick/quicknanobrowser/quicknanobrowser.exe.manifest" not found>

要将文件嵌入到可执行文件中，请将其添加到源代码中。

...

...

有关更多信息，请参阅应用程序清单文档页面。