Qt WebEngine 平台说明

从源码构建 Qt WebEngine

不支持静态构建。

在每个受支持平台上，构建 Qt 模块所需的源代码要求分别列出

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

所有平台

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

  • C++20 编译器支持
  • CMake 3.19 或更高版本
  • Python 3 与 html5lib 库
  • Bison, Flex
  • GPerf
  • Node.js 版本 14 或更高

Windows

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

  • Visual Studio 2019 或更高版本，或 clang-cl 版本 10 或更高
  • Active Template Library (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

如果为 xcb 配置了 Qt，则需要以下 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 的使用相关。此外，独立运行的 Chromium 本身未启用 App sandbox 进行官方测试，即使绕过 App Store 的限制，也不能保证库的正确行为。

双 GPU MacBooks 上的 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 页面上导致显著的性能下降。

由于这个原因，LT WebEngine在Linux上的辅助功能支持可以通过将环境变量QTWEBENGINE_ENABLE_LINUX_ACCESSIBILITY设置为0来禁用。

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

由于Windows合成器的限制，展示全屏Web引擎视图的应用程序将无法正确显示弹出窗口或其他顶层窗口。原因和解决方案在全屏基于OpenGL的窗口中描述。

Windows应用程序清单

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

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

注意：这些代码片段是从WebEngine Quick Nano Browser示例中提取的。

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
<compatibility xmlns="urn:schemas-microsoft-com:compatibility.v1">
    <application>
    <!--The ID below indicates application support for Windows Vista -->
    <supportedOS Id="{e2011457-1546-43c5-a5fe-008deee3d3f0}"/>
    <!--The ID below indicates application support for Windows 7 -->
    <supportedOS Id="{35138b9a-5d96-4fbd-8e2d-a2440225f93a}"/>
    <!--The ID below indicates application support for Windows 8 -->
    <supportedOS Id="{4a2f28e3-53b9-4441-ba9c-d69d4a4a6e38}"/>
    <!--The ID below indicates application support for Windows 8.1 -->
    <supportedOS Id="{1f676c76-80e1-4239-95bb-83d0f6d0da78}"/>
    <!--The ID below indicates application support for Windows 10/11 -->
    <supportedOS Id="{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a}"/>
    </application>
</compatibility>
</assembly>

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

    ...
qt_add_executable(quicknanobrowser
    main.cpp
    utils.h
)

if(WIN32)
    set_property(
        TARGET quicknanobrowser
        APPEND PROPERTY
            SOURCES quicknanobrowser.exe.manifest)
endif()
    ...

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

© 2024 The Qt Company Ltd. 本文档中的贡献文档版权属于其各自的所有者。提供的文档根据自由软件基金会发布并由其出版的《GNU自由文档许可协议版本1.3》下的条款进行许可。Qt及其相关标识是芬兰的The Qt Company Ltd以及全球其他国家的商标。所有其他商标均为其各自所有者的财产。