Qt WebEngine 平台注意事项

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

从源代码构建Qt WebEngine

不支持静态构建。

从源代码构建Qt模块的要求针对每个支持的平台分别列出：

  • Qt for Windows - 从源代码构建

  • Qt for X11 需求

  • Qt for macOS - 从源代码构建

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

所有平台

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

  • C++20 编译器支持

  • CMake 3.19 或更新版本

  • 使用html5lib库的Python 3

  • 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版本10或更高版本。

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 应用商店兼容性

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

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

  • 提交到App Store的应用程序必须启用App Sandbox功能进行代码签名。App Sandbox功能会干扰Chromium自身的沙盒初始化，导致Chromium无法正确初始化。这也与私有API的使用有关。此外，独立的Chromium本身并未在启用App Sandbox的情况下进行官方测试，即使绕过App Store的限制进行了工作，也不能保证库的正确行为。

MacBook 双显卡上的 macOS Airplay 支持

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

默认QSurfaceFormat OpenGL配置文件支持

如果需要设置一个新的默认QSurfaceFormat并修改OpenGL配置文件，应在声明应用程序实例之前进行设置，以确保所有创建的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》中有描述。

Windows 应用程序清单

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

以下片段展示了清单文件的结构以及如何将其嵌入到程序中。

注意

这些代码片段取自WebEngine 快速纳米浏览器示例。

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

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

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

...

...

欲了解更多信息，请参阅应用程序清单文档页面。