Qt WebEngine 平台说明

从源代码构建Qt WebEngine

不支持静态构建。

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

• Windows 版 Qt - 从源代码构建
• 用于 X11 的 Qt 要求
• 适用于 macOS 的 Qt - 从源代码构建

此外，构建 Qt WebEngine模块所需的工具：

• 所有平台
• Windows
• Linux
• MacOS

所有平台

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

• 支持 C++20 编译器
• CMake 版本至少为 3.19 或更高。
• 64 位 Nodejs 14.9 或更高版本。
• Python 3.8 或更高版本。
• Python3 html5lib 模块。
• GNU gperf 二进制文件
• GNU bison 二进制文件
• GNU flex 二进制文件。

视窗

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

• Visual Studio 2019 或更高版本。
• 如果使用 Visual Studio 2019 编译，Visual Studio 编译器版本至少为 14.29
• 如果使用 Visual Studio 2022 编译，Visual Studio 编译器版本至少为 14.36
• Windows 11 SDK 至少 10.0.26100.0 版

Linux

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

Qt WebEngine 在 Linux 环境下，运行 时需要检测其大部分依赖项。需要以下 文件：pkg-config pkg-config

• 字体配置
• Dbus

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

• x11
• libdrm
• xcomposite
• xcursor
• xrandr
• xi
• xproto
• xshmfence
• xtst
• xkbcommon
• xkbfile
• xcbdri3

macOS

在 macOS 上，需要以下文件：

• macOS 10.14 或更高版本
• Xcode 12.0 或更高版本
• macOS 11 SDK 或更高版本

使用早期 Qt 版本进行构建Qt WebEngine

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

要使用更早的 Qt 版本来构建 Qt WebEngine：

1. 下载 qtwebengine 源代码。
2. 在较早的 Qt 版本中，运行qmake && make (&& make install) 。

Mac App Store 兼容性

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

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

配备双 GPU 的 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 当满足以下条件时，Docker 可为网页提供可访问性支持：

• Qt Core 配置和构建时已启用辅助功能支持。
• 操作系统通知 QPA 插件应激活辅助功能。例如，在 Windows 上使用屏幕阅读器应用程序或在 macOS 上使用 VoiceOver 时就会出现这种情况。

在某些旧的 Linux 配置中，辅助功能可能会导致大型 HTML 页面的运行速度明显降低。

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

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

由于 Windows 合成器的限制，显示全屏网络引擎视图的应用程序无法正确显示弹出窗口或其他顶层窗口。有关原因和解决方法，请参阅《基于 OpenGL 的 Windows 全屏应用程序》。

Windows 应用程序清单

清单是一个 XML 文件，程序启动时读取该文件，并告知 Windows 如何运行程序。某些Qt WebEngine 功能可能需要添加清单文件，以便用户应用程序在 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()
    ...

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