跳转到内容
来自 Arch Linux 中文维基

Wayland 是一个旨在替代 X 窗口系统的显示服务器协议。此处有 Wayland 和 Xorg 的对比。

由于使用 Wayland 协议的显示服务器也可作为混成窗口管理器,因此被称为混成器(compositors)。你可以在#混成器中找到相关信息。

为了兼容原生 X11 应用程序,使其在 Wayland 中无缝运行,可以使用 #Xwayland,它在 Wayland 中提供了 X 服务器。

系统需求

大多数 Wayland 混成器只能在使用了 Kernel mode setting 的系统上工作。Wayland 本身并不提供图形环境;为此还需要安装混成器(参见下一节),或者内置混成器的桌面环境,比如 GNOMEPlasma

GPU 驱动程序与 Wayland 混成器必须支持相同的缓冲区 API (Buffer API) 才能够互相兼容。现在主要有两种 API:GBMEGLStreams

缓冲区 API GPU 驱动支持 Wayland 混成器支持
GBM 除版本号低于 495 的 NVIDIA 驱动,均支持 全部
EGLStreams NVIDIA GNOME
* 版本 ≥ 495 的 NVIDIA 驱动同时支持 EGLStreams 和 GBM。[1]

自 NVIDIA 在版本 495 引入 GBM 支持以来,许多合成器 (包括 Mutter 和 KWin) 都开始默认使用 GBM 。通常认为 GBM 更好,有更为广泛的支持,而以前仅支持 EGLStreams 是因为之前无法在 Wayland 下通过专有驱动程序来使用 NVIDIA GPU。此外,在 NVIDIA 支持 GBM 后,KWin 放弃了对 EGLStreams 的支持[2]

如果您使用的是流行的桌面环境/混成器,GPU 也受 NVIDIA 支持,那么很可能已经在使用 GBM 后端了。要检查是否使用 GBM 后端,请执行 journalctl -b 0 --grep "renderer for"。要强制使用 GBM 后端,请设置以下环境变量

GBM_BACKEND=nvidia-drm
__GLX_VENDOR_LIBRARY_NAME=nvidia

混成器

堆叠式平铺式动态的区别参见窗口管理器#类型

堆叠式

https://www.enlightenment.org/ || enlightenment
  • hikari — 基于 wlroots 并受 cwm 启发开发,在 FreeBSD 上开发很活跃,但也支持 Linux。
https://web.archive.org/web/20241220075628/https://hikari.acmelabs.space/ || hikariAUR
https://userbase.kde.org/KWin || kwin
  • Liri ShellLiri 一部分,其使用 QtQuick 和 QtCompositor 为 Wayland 构建。
https://github.com/lirios/shell || liri-shell-gitAUR
  • labwc — 基于 wlroots 并受 Openbox 启发的混成器。
https://github.com/labwc/labwc || labwc
https://gitlab.gnome.org/GNOME/mutter || mutter
  • wayfire — 3D 混成器,受 Compiz 启发并基于 wlroots 开发。
https://wayfire.org/ || wayfireAUR
  • Weston — Wayland 混成器,设计注重正确性、可靠性、可预测性和性能。
https://gitlab.freedesktop.org/wayland/weston || weston
  • wio — 基于 wlroots 的混成器,致力于复刻 Plan 9 的 Rio 桌面的外观和质感。
https://gitlab.com/Rubo/wio || wio-wlAUR

平铺式

https://github.com/project-repo/cagebreak || cagebreakAUR
  • miracle-wm — 基于 Mir 的 Wayland 混成器,风格类似 i3 和 sway,旨在比两者更炫目且功能更丰富,如 swayfx。
https://github.com/miracle-wm-org/miracle-wm || miracle-wmAUR
  • niri — 可滚动的平铺式 Wayland 混成器。
https://github.com/YaLTeR/niri/ || niri
  • Qtile — 功能齐全、可定制性强的平铺式窗口管理器和 Wayland 混成器,使用 Python 开发、配置。
https://github.com/qtile/qtile || qtile
  • Sway — 基于 wlroots、与 i3 兼容的 Wayland 混成器。
https://github.com/swaywm/sway || sway
  • SwayFxSway,但带有视觉效果!
https://github.com/WillPower3309/swayfx || swayfxAUR
  • Velox — 基于 swc 的简单窗口管理器,受 dwm 和 xmonad 启发。
https://github.com/michaelforney/velox || velox-gitAUR

动态

  • dwl — 基于 wlroots、类似 dwm 的 Wayland 混成器。
https://codeberg.org/dwl/dwl || dwlAUR
  • Hyprland — 不以牺牲外观为代价的动态 Wayland 平铺混成器。
https://hyprland.org || hyprland
  • japokwm — 基于 wlroots 创建布局的动态 Wayland 平铺混成器。
https://github.com/werererer/japokwm || japokwm-gitAUR
  • river — 受 dwm 和 bspwm 启发的动态平铺 Wayland 混成器。
https://codeberg.org/river/river || river
  • Vivarium — 使用 wlroots 的动态平铺 Wayland 混成器,桌面部分受 xanmod 启发。
https://github.com/inclement/vivarium || vivarium-gitAUR

其它类型

  • Cage — 显示单个全屏应用程序(就像自助取款机那样)。
https://www.hjdskes.nl/projects/cage/ || cage
  • phoc — 适用于移动设备的基于 wlroots 的轻量混成器。
https://gitlab.gnome.org/World/Phosh/phoc || phoc

上述某些混成器/窗口管理器支持显示管理器。请查看 /usr/share/wayland-sessions/compositor.desktop 文件来了解如何启动显示上述混成器/窗口管理器。

显示管理器

下面列出的显示管理器均支持启动 Wayland 混成器。

名称 在 Wayland 上运行 描述
emptty 简单的 TTY CLI 显示管理器。
GDM GNOME 的显示管理器。
greetd 使用 Wayland 登录程序时 极简且使用灵活的登录守护程序。
lemurs 用 Rust 编写的 TUI 显示管理器。
LightDM 跨桌面显示管理器。
ly 用 C 语言编写的 TUI 显示管理器。
SDDM 基于 QML 开发的显示管理器。
tbsmAUR 用纯 Bash 编写的简单 CLI 会话启动器。
uwsm 利用 Systemd 机制的独立混成器会话和 XDG 自动启动管理器。

Xwayland

Xwayland(1) 是一个在 Wayland 下运行的 X 服务器,为尚未提供 Wayland 支持的原生 X11 应用程序提供兼容性。要使用它,请 安装 xorg-xwayland 包。

Xwayland 通过合成器启动,因此您应查看所选合成器的文档,以了解 Xwayland 的兼容性以及如何启动 Xwayland。

注意:
  • 安全性:Xwayland 是一个 X 服务器,因此它不具备 Wayland 的安全特性。
  • 性能:Xwayland 的性能与 X11 几乎相同。在某些情况下,您可能会注意到性能下降,尤其是在 NVIDIA 显卡上。
  • 兼容性:Xwayland 并不完全向后兼容 X11。某些应用程序在 Xwayland 下可能无法正常工作。

NVIDIA 驱动

注意:470 版本之前的 NVIDIA 驱动(例如 nvidia-390xx-dkmsAUR)不支持硬件加速的 Xwayland,导致非 Wayland 原生应用程序在 Wayland 会话中性能不佳。

需要启用 DRM KMS。有关您的显示管理器(例如 GDM)的更多信息,请参阅 官方文档

Kwin Wayland 调试控制台

如果您使用 kwin,可以执行以下命令来查看哪些窗口使用 Xwayland 或原生 Wayland、表面、输入事件、剪贴板内容等。

$ qdbus6 org.kde.KWin /KWin org.kde.KWin.showDebugConsole

视觉上检测 Xwayland 应用程序

要确定应用程序是否通过 Xwayland 运行,您可以运行 extramausAUR。 将鼠标指针移动到应用程序的窗口上。如果红色鼠标移动,则应用程序通过 Xwayland 运行。

或者,您可以使用 xorg-xeyes,看看当鼠标指针移动到应用程序窗口上时,眼睛是否在移动。

另一个选项是在终端窗口中运行 xwininfo(来自 xorg-xwininfo):当悬停在 Xwayland 窗口上时,鼠标指针会变成 + 号。如果您点击窗口,它将显示一些信息并结束,但对于原生 Wayland 窗口则不会执行任何操作。您可以使用 Ctrl+C 来结束它。

您还可以使用 xlsclients(来自 xorg-xlsclients 包)。要列出所有通过 Xwayland 运行的应用程序,请运行 xlsclients -l

图形库

详情请查看官方网站[失效链接 2024-10-12 ⓘ]

GTK

gtk3gtk4 包已经提供了 Wayland 支持。GTK 默认使用 Wayland 后端,但是可以通过修改环境变量为 GDK_BACKEND=x11 覆盖默认设置切换到 XWayland。

关于主题问题,请参阅 GTK#Wayland_后端

Qt

要在 Qt 5 或 6 中启用 Wayland 支持,请分别安装 qt5-waylandqt6-wayland 软件包。Qt 应用程序将在 Wayland 会话下运行。

虽然通常不需要,但若要显式使用 Wayland 插件运行 Qt 应用程序 [5],请使用 -platform waylandQT_QPA_PLATFORM=wayland 环境变量

要在 Wayland 会话中强制使用 X11,请使用 QT_QPA_PLATFORM=xcb。这对于某些不使用系统 Qt 实现的应用(比如 zoomAUR)可能是必需的。QT_QPA_PLATFORM="wayland;xcb" 允许 Qt 在 Wayland 不可用时使用 xcb (X11) 插件 [6]

由于 Qt WebEngine 在 Wayland 上使用分数缩放时出现错误尺寸和文本渲染问题 的 Qt WebEngine 错误,使用 Qt WebEngine 的应用程序(例如 Calibre)可能会显示锯齿字体。一个解决方法是启动应用程序时设置 QT_SCALE_FACTOR_ROUNDING_POLICY=RoundPreferFloor,这可以防止应用程序窗口进行分数缩放。

Clutter

Clutter 工具包有 Wayland 后端支持,可以作为 Wayland 客户端运行。此后端支持已在官方软件包 clutter 中启用。

要在 Wayland 上运行 Clutter 应用,请设置 CLUTTER_BACKEND=wayland 环境变量。

SDL

SDL3 中,Wayland 默认用于与桌面合成器通信。

要在 Wayland 上运行 SDL2 应用,请设置 SDL_VIDEODRIVER=waylandSDL_VIDEODRIVER="wayland,x11" 允许 SDL2 在 Wayland 不可用时使用 x11 视频驱动 [7]。你可能还需要安装 libdecor 以启用窗口装饰(例如在 GNOME 上)。

参见官方说明

GLFW

glfw 包支持 Wayland,如果 环境变量 XDG_SESSION_TYPE 设置为 wayland,并且应用程序开发人员没有设置特定的后端,则使用 Wayland 后端。

查看 源代码 以获取更多信息。

GLEW

如果 glew-wayland-gitAUR 包无法与所需的 GLEW 应用程序一起使用,则可以使用 glew 和 Xwayland。参见 FS#62713

EFL

EFL 已经完全支持 Wayland。要在 Wayland 上运行 EFL 应用,请参阅 Wayland 项目页面[失效链接 2024-10-12 ⓘ]

winit

Winit 是 Rust 语言中的窗口处理库。默认使用 Wayland 后端,但可以通过修改环境变量将其切换到 Xwayland:

  • 在 0.29.2 版本之前,设置 WINIT_UNIX_BACKEND=x11
  • 对于 0.29.2 及更高版本,取消设置 WAYLAND_DISPLAY,这将强制回退到使用 DISPLAY 变量的 X [8]

Electron

可以通过为每个应用程序单独添加命令行参数或使用配置文件来激活 Wayland 支持。详情请参阅 #配置文件

要确定应用程序使用的 Electron 版本,请参阅 [9]

注意:在 Plasma 中,某些 Electron 应用程序可能会使用错误的图标(默认的 Wayland 图标)作为窗口图标,而任务栏图标是正确的。要解决此问题,可以创建一个特殊的应用程序/窗口规则,强制此类应用程序使用桌面文件名称。

环境变量

使用 Electron 28 及更高版本的应用程序可以使用 环境变量 ELECTRON_OZONE_PLATFORM_HINT 设置为 autowayland

此设置的优先级低于命令行参数。

命令行参数

与基于 Chromium 的 Electron 不同,Electron 应用程序默认不启用基于 PipeWire 的 WebRTC 屏幕捕获。因此,建议使用 --enable-features=WebRTCPipeWireCapturer 以避免在 Wayland 上出现屏幕捕获问题。捕获基于 xdg-desktop-portal

要在 Wayland 上原生使用 electron 应用程序,当使用环境变量不可行或不理想时,可以在 Electron 20+ 中添加 --ozone-platform-hint=auto

缺少顶部栏的问题可以通过使用 --enable-features=WaylandWindowDecorations 解决。这在 GNOME 下通常是必要的(自 electron17 开始支持)。

你可以通过 修改 .desktop 文件 并将这些参数添加到 Exec= 行的末尾来更永久地设置这些参数,或者更干净地使用下面描述的配置文件。

注意:某些软件包不会将参数传递给 Electron,因此需要应用程序开发者实现解决方案。

配置文件

Electron 软件包读取 ~/.config/electronXX-flags.conf 文件,其中 XX 是 Electron 版本,如果版本文件不存在,则回退到共享的 ~/.config/electron-flags.conf

将上述参数每行一个地放入文件中:

~/.config/electron-flags.conf
--enable-features=WaylandWindowDecorations
--ozone-platform-hint=auto
注意:这些配置文件仅对官方仓库的 Electron 软件包和使用这些 Electron 包的应用程序有效。对于自带 Electron 的软件包(如 slack-desktopAUR)来说,这些配置文件是无效的。不过在某些情况下也有替代品,如 slack-electronAUR

旧版本 Electron

electron25-flags.conf 仅适用于 Electron 25 版本。旧版本的 Electron 可以使用各自的 electron<version>-flags.conf 文件进行配置。

旧版本可能需要不同的参数,具体取决于相应的 Chromium 版本。例如,以下参数适用于 Electron 13:

~/.config/electron13-flags.conf
--enable-features=UseOzonePlatform
--ozone-platform=wayland

无法使用fcitx5输入法

在支持text_input_v1协议的合成器上,你可以尝试添加--enable-wayland-ime标示。

详见 Chromium#原生 Wayland 上运行

无法使用ibus输入法

在不支持text_input_v1协议的合成器(如ibus)上,你需要额外添加--enable-wayland-ime --wayland-text-input-version=3标示,以设置electron应用使用v3协议。

详见 Chromium#原生 Wayland 上运行

Java

Java 平台的开源实现 OpenJDK 尚未原生支持 Wayland。在 Wakefield 项目(旨在在 OpenJDK 中实现 Wayland)可用之前,可以使用 Xwayland。

参见 Debian:Wayland#Java Programs (supported since OpenJDK 16?)

从 OpenJDK 16 开始,JRE 可以动态加载 GTK3(支持 Wayland),根据此 讨论,这似乎是支持的。
可以设置 _JAVA_AWT_WM_NONREPARENTING 环境变量 为 "1" 以修复应用程序启动时出现空白屏幕的问题。

由于 XWayland 没有与 Wayland 完全的功能对等,WLToolkit 可以在 Wakefield 未准备好时填补空白。可以通过 -Dawt.toolkit.name=WLToolkit 激活。一些程序(如 JetBrains IDE 支持它)。

提示与技巧

自动化

重新映射键盘或鼠标按键

参见 输入重映射工具

使用 X11 应用程序录制 Wayland 窗口

参见 屏幕捕获#通过_X11_应用程序投射_Wayland_屏幕

Chromium 无法完全最大化

您需要通过 chrome://settings/appearance 菜单启用 使用系统标题栏和边框

应用程序关闭后保留剪贴板内容

本文或本章节可能需要合并到Clipboard

附注: 这是 Xorg 上的标准行为。还有许多其他剪贴板管理器。(在 Talk:Wayland 中讨论)

由于 Wayland 的设计理念,剪贴板数据存储在源客户端的内存中。当客户端关闭时,剪贴板数据将丢失。您可以使用 wl-clip-persist 来解决这个问题,它在后台运行以读取剪贴板数据并将其存储在自己的内存中,与源客户端分离。

使用 systemd 服务自动启动 Wayland 合成器

如果您不想使用显示管理器或 shell, 您可以尝试通过上述 systemd 服务自动启动 Wayland 合成器。将 labwc 替换为您想要使用的合成器。

/etc/systemd/system/labwc.service
[Unit]
After=graphical.target systemd-user-sessions.service dev-dri-card0.device
Wants=dev-dri-card0.device
Conflicts=getty@tty1.service

[Service]
Type=simple
User=yourusername
WorkingDirectory=~

PAMName=login
TTYPath=/dev/tty1
UnsetEnvironment=TERM

StandardOutput=journal
ExecStart=/bin/labwc

[Install]
WantedBy=graphical.target

其中 dev-dri-card0.device 由 udev 规则生成

/etc/udev/rules.d.99-dri.rules
ACTION=="add", SUBSYSTEM=="drm", KERNEL=="card0", TAG+="systemd"
注意:为了物理安全,您可能需要通过合成器的设置自动运行屏幕锁定程序,例如 swaylock。

在基于 wlroots 的混成器上使用另一个渲染器

您可以通过为基于 wlroots 的混成器设定 WLR_RENDERER 环境变量以使用另一个 wlroots 渲染器如 vulkan。请参阅 wlroots 文档以查找可用的渲染器。

故障排除

颜色校正

请参阅背光#色彩校正

慢动作、图形显示故障和崩溃

Gnome-shell 用户从 X 切换到 Wayland 时可能会遇到此问题。根本原因之一是可能用户自己为基于 Xorg 的 gnome-shell 设置了 CLUTTER_PAINT=disable-clipped-redraws:disable-culling 变量。只需尝试将变量从 /etc/environment 或其它 rc 文件中移除,即可查看是否一切恢复正常。

远程显示

  • sway 使用的 wlroots 从 0.10 版本开始通过 wayvnc 提供了一个 VNC 后端。RDP 后端则已被移除。[10]
  • 目前 mutter 在编译时就启用了远程桌面功能,详情请参阅 [11]gnome-remote-desktop
  • krfbkwin 提供了一个 VNC 服务器。krfb-virtualmonitor 可用于将另一台设备设置为额外的显示器。
  • 在 2013 年 Weston 合并了对 FreeRDP 的支持,可通过编译标志 (compile flag) 启用。weston 自 6.0.0 版本开始启用了 FreeRDP。
  • waypipe (或 waypipe-gitAUR) 是适用于 Wayland 应用的透明代理,可通过封装的命令在 SSH 上运行。
    • 以下是一个在 Plasma 下启动远程 KDE kcalc 的示例:
$ waypipe ssh example.local env QT_QPA_PLATFORM=wayland-egl QT_QPA_PLATFORMTHEME=KDE dbus-launch kcalc

游戏、远程桌面和虚拟机窗口中的输入捕获问题

与 Xorg 不同的是,Wayland 并不允许独占输入设备捕获 (也被称为主动捕获或显式捕获,比如键盘鼠标等设备)。Wayland 依赖混成器传递键盘快捷键,并将指针设备限制在应用窗口中。

输入捕获方式的变化破坏了当前应用程序的行为,意味着:

  • 热键组合和修饰符输入会被混成器捕获,并且不会发送到远程桌面和虚拟机窗口中。
  • 鼠标指针将不会被限制在应用程序的窗口中,这可能会导致视差效应,即虚拟机或远程桌面的窗口内鼠标指针的位置与主机的鼠标指针发生偏差。

Wayland 通过为 Wayland 和 XWayland 添加协议扩展来解决此问题。为此 Wayland 混成器需要添加对这些扩展的支持。如果是本地 Wayland 客户端,其使用的部件工具集 (widget toolkits,比如 GTK,Qt) 需要支持这些插件;如果没有使用部件工具集,则需要支持应用程序本身。如果是 Xorg 应用程序,则不需要改变应用程序或者部件工具集,因为 XWayland 的支持就足够了。

wayland-protocols 中已经包含了这些扩展, 并由 xorg-xwayland 支持。

相关的扩展有:

支持的 Wayland 混成器有:

支持的部件工具集有:

  • GTK,从 3.22.18 版本开始支持。

GTK 主题没有生效

请查看 https://github.com/swaywm/sway/wiki/GTK-3-settings-on-Wayland.

避免加载 NVIDIA 模块

在 Wayland 混成器(如 sway)启动之前,将 __EGL_VENDOR_LIBRARY_FILENAMES=/usr/share/glvnd/egl_vendor.d/50_mesa.json 添加到系统环境变量中。

放大/表面缩放

屏幕放大问题尚未解决,2022 年中合并了一个拉取请求 提供了 wp-surface-scale 协议

Wayland 卡顿/延迟(自内核 6.11.2,AMD)

在此问题在未来的内核版本中修复之前,一个临时解决方案是在 cmdline 中添加 amdgpu.dcdebugmask=0x400

参见:https://community.frame.work/t/wayland-lag-stuttering-since-kernel-6-11-2/59422

另请参阅