Qt WebEngine 平台注意事项

从源代码构建 Qt WebEngine

静态构建不被支持。

分别列出从源代码构建 Qt 5 模块的要求,对于各个支持平台:

此外,需要以下工具为构建 Qt WebEngine 模块:

跳过 Qt WebEngine 构建的测试位于 qtwebengine 存储库,在 tools\qmake\mkspecs 子目录。可以找到它们通过搜索 skipBuild .

所有平台

On all platforms, the following tools are required at build time:

  • Python 2.7.5 或更高版本。不支持 Python 3。
  • Bison, Flex
  • GPerf
  • Node.js version 8 or later (version 12 or later is recommended)

Windows

在 Windows,需要以下额外工具:

  • Visual Studio 2017 version 15.8 or later, or clang-cl version 8 or later
  • ATL (活动模板库),通常包括在 Visual Studio 安装中
  • Windows 10 SDK version 10.0.19041 or later

Qt WebEngine 只能在带有 x64 位工具链的 64 位 Windows 中进行构建。为构建用于 x86 应用程序的 Qt WebEngine,需要采用 Visual Studio 2017 x64 to x86 交叉编译工具链来配置和编译 Qt。可以在命令行中设置此工具链,通过运行 vcvarsall.bat amd64_x86 .

Linux

在 Linux,需要 Clang 或 GCC 第 5 版或更高版本。支持配置 linux-g++ , linux-clang and linux-clang-libc++

Qt WebEngine 要求 pkg-config 以检测其大多数依赖。以下 pkg-config 文件要求:

  • dbus-1
  • fontconfig

若 Qt 被配置为 xcb ,以下 pkg-config 文件也是必需的:

  • libdrm
  • xcomposite
  • xcursor
  • xi
  • xrandr
  • xscrnsaver
  • xtst

进一步,开发包为 khr and libcap 需要安装。

macOS

在 macOS,需要以下:

  • macOS 10.13 或更高版本
  • Xcode 10.0 或更高版本
  • macOS 10.13 SDK 或更高版本

注意: 无法为 macOS 的 32 位模式构建 Qt WebEngine (使用 macx-clang-32 mkspec ).

注意: Universal debug or debug-and-release builds of Qt WebEngine on macOS are not supported in Qt 5 due to memory constraints of the build toolchain. Use the configure options -force-debug-info and -separate-debug-info for a build that can be used with a debugger.

使用早期 Qt 版本构建 Qt WebEngine

支持采用早期版本 (到最新 LTS 版本) 的 Qt 构建 Qt WebEngine。意味着可以采用 Qt 5.12.x、Qt 5.14.x 及 Qt 5.15构建 Qt WebEngine 5.15。

要使用早期 Qt 版本构建 Qt Webengine:

  1. 下载 qtwebengine 源代码。
  2. 从早期 Qt 版本运行 qmake && make (&& make install) .

Mac APP 商店兼容性

Applications using Qt WebEngine are not compatible with the Mac App Store, because:

  • The Chromium part of the code uses several private API methods, which are prohibited by the App Store.
  • Applications submitted to the App Store must be code-signed with the App Sandbox feature enabled. The App Sandbox feature interferes with Chromium's own sandbox initialization, which results in Chromium not being properly initialized. This also ties in with the private API usage. Furthermore, standalone Chromium itself is not officially tested with the App Sandbox enabled, and even if work is done to bypass the App Store's restrictions, that would not guarantee correct behavior of the library.

支持带双 GPU 的 MacBook macOS Airplay

To make Qt WebEngine work correctly when streaming to an AppleTV from a MacBook that supports GPU switching, it is important to add the NSSupportsAutomaticGraphicsSwitching option to the application Info.plist file, with the value set to YES . Otherwise rendering issues might occur when creating new web engine view instances after Airplay is switched on or off.

默认支持 QSurfaceFormat OpenGL Profile (配置文件)

If a new default QSurfaceFormat with a modified OpenGL profile has to be set, it should be set before the application instance is declared, to make sure that all created OpenGL contexts use the same OpenGL profile.

On macOS, if the default QSurfaceFormat is set after the application instance, the application will exit with qFatal (), and print a message that the default QSurfaceFormat should be set before the application instance.

沙盒支持

Qt WebEngine 为 Chromium 渲染过程提供开箱即用的沙盒支持。

在 Linux,注意以下限定:

  • 内核必须支持匿名名称空间特征 (内核版本 3.8 或更高版本)。不管怎样,在 Debian、Ubuntu 且其它 Debian 派生分发,此特征是关闭的默认情况下。可以打开它通过设置 /proc/sys/kernel/unprivileged_userns_clone to 1.
  • 内核必须支持 seccomp-bpf 特征 (内核版本 3.5 或更高版本)。
  • Setuid 沙盒不受支持,因此被禁用。

要明确禁用沙盒,使用以下选项之一:

  • 设置 QTWEBENGINE_DISABLE_SANDBOX 环境变量到 1。
  • 传递 --no-sandbox 命令行自变量,给用户应用程序可执行文件。
  • Set QTWEBENGINE_CHROMIUM_FLAGS to --no-sandbox .

更多信息,见 使用命令行参数 .

Docker 环境下的内存需求

当在 Docker 容器中运行 Qt WebEngine 范例并浏览内容繁重站点时,可能报告 BUS 错误 (SIGBUS)。通常,这是由于 Docker 运行过小内存空间 (譬如 64MB) 容器导致的。要修复此问题,增加内存空间大小。

可访问性和性能

Qt WebEngine enables accessibility support for web pages when the following conditions are met:

  • Qt Core is configured and built with accessibility support enabled.
  • The QPA plugin is notified by the operating system that accessibility should be activated. This happens for example when using a screen reader application on Windows or VoiceOver on macOS.

On some old Linux configurations, accessibility can cause a significant slowdown on large HTML pages.

Because of that, Qt WebEngine accessibility support can be disabled on Linux, by setting the QTWEBENGINE_ENABLE_LINUX_ACCESSIBILITY environment variable to 0.

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

Because of a limitation in the Windows compositor, applications that show a fullscreen web engine view will not properly display popups or other top-level windows. The reason and workaround for the issue can be found at 基于 OpenGL 的窗口全屏 and QWindowsWindowFunctions::setHasBorderInFullScreen .