Wayland

Wayland 是一个显示服务器协议。它已被广泛确立为 X Window System 的继任者 [1] [2] [3] [4]。你可以在 Wikipedia 上找到 Wayland 和 Xorg 之间的比较。

使用 Wayland 协议的显示服务器称为 **合成器 (compositors)**，因为它们也充当合成窗口管理器。下面你可以找到一个 Wayland 合成器列表。

为了与原生 X11 应用程序兼容，可以无缝运行它们，可以使用 Xwayland，它在 Wayland 中提供了一个 X 服务器。

需求

大多数 Wayland 合成器仅在使用内核模式设置 (Kernel mode setting) 的系统上工作。Wayland 本身不提供图形环境；为此，你还需要一个合成器（参见下一节），或者一个包含合成器的桌面环境（例如 GNOME 或 Plasma）。

为了使 GPU 驱动程序和 Wayland 合成器兼容，它们必须支持相同的缓冲区 API。有两种主要的 API：GBM 和 EGLStreams。

缓冲区 API	GPU 驱动支持	Wayland 合成器支持
GBM	除 NVIDIA < 495* 外均支持	全部支持
EGLStreams	NVIDIA	GNOME

* NVIDIA ≥ 495 同时支持 EGLStreams 和 GBM。[5]

自从 NVIDIA 引入 GBM 支持以来，许多合成器（包括 Mutter 和 KWin）开始默认使用它来支持 NVIDIA ≥ 495。GBM 通常被认为支持更广泛，而 EGLStreams 仅因 NVIDIA 在其专有驱动程序下未提供其他方式使用其 GPU 而获得支持。此外，KWin 在引入 NVIDIA 的 GBM 支持后放弃了对 EGLStreams 的支持。

如果你使用的是流行的桌面环境/合成器，并且 GPU 仍然受到 NVIDIA 支持，那么你很可能已经在使用 GBM 后端。要进行检查，请运行 journalctl -b 0 --grep "renderer for"。要强制使用 GBM 作为后端，请设置以下环境变量

GBM_BACKEND=nvidia-drm
__GLX_VENDOR_LIBRARY_NAME=nvidia

合成器

有关 **堆叠式 (Stacking)**、**平铺式 (Tiling)** 和 **动态式 (Dynamic)** 之间的区别，请参见窗口管理器#类型。

堆叠式

COSMIC Compositor — COSMIC 桌面环境的合成器。

https://github.com/pop-os/cosmic-comp || cosmic-comp

hikari — 基于 wlroots 的合成器，受 cwm 启发，在 FreeBSD 上积极开发，但也支持 Linux。

http://hikari.acmelabs.space/ || hikari^AUR

KDE KWin — 参见 KDE#启动 Plasma。

https://userbase.kde.org/KWin || kwin

labwc — 基于 wlroots 的合成器，受 Openbox 启发。

https://github.com/labwc/labwc || labwc

Mutter — 参见 GNOME#启动。

https://gitlab.gnome.org/GNOME/mutter || mutter

waybox — 一个 *box 风格（极简）的 Wayland 合成器，很大程度上模仿 Openbox

https://github.com/wizbright/waybox || waybox^AUR

wayfire — 3D 合成器，受 Compiz 启发，基于 wlroots。

https://wayfire.org/ || wayfire^AUR

Weston — Wayland 合成器，设计用于正确性、可靠性、可预测性和性能。

https://gitlab.freedesktop.org/wayland/weston || weston

wio — 基于 wlroots 的合成器，旨在复制 Plan 9 的 Rio 桌面的外观和感觉。

https://gitlab.com/Rubo/wio || wio-wl^AUR

wlmaker — 基于 wlroots 的合成器，受 Window Maker 启发。

https://phkaeser.github.io/wlmaker/ || wlmaker^AUR

woodland — 一个最小化的轻量级 wlroots 合成器，用于 Wayland，受 Wayfire 和 TinyWl 启发。

https://github.com/DiogenesN/woodland || woodland^AUR

平铺式

Cagebreak — 基于 cage，受 ratpoison 启发。

https://github.com/project-repo/cagebreak || cagebreak^AUR

miracle-wm — 一个基于 Mir 的 Wayland 合成器，风格类似于 i3 和 sway，旨在比两者都更华丽、功能更丰富，类似于 swayfx。

https://github.com/miracle-wm-org/miracle-wm || miracle-wm^AUR

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

SwayFx — Sway，但带有华丽效果！

https://github.com/WillPower3309/swayfx || swayfx^AUR

Velox — 基于 swc 的简单窗口管理器，受 dwm 和 xmonad 启发。

https://github.com/michaelforney/velox || velox-git^AUR

动态式

cwc — 基于 wlroots 的类似 awesome 的 Wayland 合成器。

https://cudiph.github.io/cwc/apidoc/ || cwc^AUR

MangoWC — 一个基于 dwl 的合成器，具有标准配置文件，可选的滚动布局和华丽效果支持。

https://github.com/DreamMaoMao/mangowc || mangowc^AUR

dwl — 基于 wlroots 的类似 dwm 的 Wayland 合成器。

https://codeberg.org/dwl/dwl || dwl^AUR

Hyprland — 一个动态平铺式 Wayland 合成器，不牺牲外观。

https://hypr.land || hyprland

japokwm — 动态 Wayland 平铺式合成器，基于 wlroots，侧重于创建布局。

https://github.com/werererer/japokwm || japokwm-git^AUR

river — 动态平铺式 Wayland 合成器，受 dwm 和 bspwm 启发。

https://codeberg.org/river/river || river

其他

Cage — 显示单个全屏应用程序，如信息亭。

https://www.hjdskes.nl/projects/cage/ || cage

GNOME Kiosk — 基于 Mutter 的合成器，提供适合固定用途或单应用程序部署的环境，如墙面显示器和销售点系统。

https://gitlab.gnome.org/GNOME/gnome-kiosk || gnome-kiosk^AUR

phoc — 一个微小的 wlroots 合成器，用于移动设备。

https://gitlab.gnome.org/World/Phosh/phoc || phoc

Wayback — X11 兼容层，允许使用 Wayland 组件运行完整的 X11 桌面环境。它还在开发早期阶段，是实验性的。

https://wayback.freedesktop.org/ || wayback-x11^AUR

上述部分合成器可能支持显示管理器。检查 /usr/share/wayland-sessions/compositor.desktop 以了解它们是如何启动的。

显示管理器

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

名称	运行在	描述
emptty	tty	TTY 上的简单命令行显示管理器。
GDM	Wayland	GNOME 显示管理器。
greetd	Wayland/Xorg/tty 参见 Greetd#Greeters。	极简且灵活的登录守护进程。
lemurs	tty	用 Rust 编写的 TUI 显示管理器。
lidm^AUR	tty	一个完全彩色可定制的 TUI 显示管理器，用 C 编写。
LightDM	Xorg[6]	跨桌面显示管理器。
ly	tty	用 Zig 编写的 TUI 显示管理器
SDDM	Wayland/Xorg	基于 QML 的显示管理器。
tbsm^AUR	tty	用纯 bash 编写的简单命令行会话启动器。
uwsm	tty	独立合成器的会话和 XDG 自启动管理器。提供 TUI 菜单，但也可与其他显示管理器一起使用。

Xwayland

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

Xwayland 通过合成器启动，因此您应该查阅您选择的合成器的文档以了解 Xwayland 兼容性和启动 Xwayland 的说明。

注

安全性：Xwayland 是一个 X 服务器，因此它不具备 Wayland 的安全特性。
性能：在大多数情况下，Xwayland 的性能几乎与 X11 相同。
兼容性：Xwayland 与 X11 的向后兼容性不完善。某些应用程序可能无法在 Xwayland 下正常工作。

Wayback

Wayback（wayback-x11^AUR, wayback-x11-git^AUR）是一个 X11 兼容层，它允许使用 Wayland 组件运行完整的 X11 桌面环境。它旨在最终取代传统的 X.Org 服务器，从而减轻 X11 应用程序的维护负担。

NVIDIA 驱动

注意 470 版本之前的 NVIDIA 驱动程序（例如 nvidia-390xx-dkms^AUR）不支持硬件加速 Xwayland，导致非 Wayland 原生应用程序在 Wayland 会话中性能低下。

需要启用 DRM KMS。关于您的显示管理器（例如 GDM），您可能可以在官方文档中找到额外信息。

检测 Xwayland 应用程序

要确定应用程序是否通过 Xwayland 运行，可以使用 xorg-xeyes，并在将鼠标指针移到应用程序窗口上时观察眼睛是否移动。

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

您也可以使用 xlsclients（来自 xorg-xlsclients 包）。要列出所有通过 Xwayland 运行的应用程序，请运行 xlsclients -l。

或者，您可以启动 extramaus^AUR 并将鼠标指针悬停在应用程序的窗口上。如果红色鼠标移动，则该应用程序正在通过 Xwayland 运行。

提示对于 KDE Plasma，您也可以使用 KDE#KWin 调试控制台来检查窗口。

GUI 库

GTK

gtk3 和 gtk4 包已启用 Wayland 后端。GTK 将默认使用 Wayland 后端，但可以通过修改环境变量来覆盖为 Xwayland：GDK_BACKEND=x11。

有关主题问题，请参见 GTK#Wayland 后端。

Qt

要启用 Qt 5 中的 Wayland 支持，请安装 qt5-wayland 包。然后，Qt 5 应用程序将在 Wayland 会话下运行在 Wayland 上。

虽然不应该有必要，但要显式使用 Wayland 插件运行 Qt 应用程序 [7]，可以使用 -platform wayland 或 QT_QPA_PLATFORM=wayland 环境变量。

要在 Wayland 会话中强制使用 X11，请使用 QT_QPA_PLATFORM=xcb。

这可能对一些不使用系统 Qt 实现的专有应用程序是必要的。QT_QPA_PLATFORM="wayland;xcb" 允许 Qt 在 Wayland 不可用时改用 xcb (X11) 插件。[8]

本文或本章节的准确性存在争议。

原因: 感觉不对或过时。我不知道其他潜在的应用程序，但 KeepassXC 在 Sway 下正常最小化到托盘不需要任何这些（在 Talk:Wayland 中讨论）

在某些合成器上，例如 sway，原生运行的 Qt 应用程序可能缺少功能。例如，KeepassXC 将无法最小化到托盘。这可以通过安装 qt5ct 并先于应用程序运行 QT_QPA_PLATFORMTHEME=qt5ct 来解决。

由于在 Wayland 上使用分数缩放时 WebEngine 的尺寸不正确和文本渲染效果差的 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=wayland。SDL_VIDEODRIVER="wayland,x11" 允许 SDL2 在 Wayland 不可用时改用 x11 视频驱动程序。[9]。您可能还想安装 libdecor 以启用窗口装饰（例如，在 GNOME 上）。

有关更多详细信息，请参阅官方文档。

GLFW

glfw 包支持 Wayland，如果环境变量 XDG_SESSION_TYPE 设置为 wayland 并且应用程序开发者未设置特定的所需后端，它将使用 Wayland 后端。

有关更多信息，请参见源代码。

GLEW

如果 glew-wayland-git^AUR 包无法与所需的基于 GLEW 的应用程序一起工作，则选项是使用 glew 配合 Xwayland。参见 FS#62713。

EFL

Enlightenment 具有完整的 Wayland 支持。

要在 Wayland 上运行 EFL 应用程序，请设置 ELM_DISPLAY=wl。

winit

Winit 是 Rust 中的一个窗口处理库。它将默认使用 Wayland 后端，但可以通过修改环境变量来覆盖为 Xwayland

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

Electron

注意在 KDE Plasma 中，某些 Electron 应用程序在窗口中使用不正确的图标（默认 Wayland 图标），而在任务栏中使用正确的图标。要解决此问题，您可以创建一个特殊的应用程序/窗口规则，强制为此类应用程序设置桌面文件名称。

可以通过命令行标志或环境变量来激活 Wayland 支持。

自 Electron 38 起，Wayland 已默认启用，环境变量和命令行标志已被弃用且无效。

命令行标志

注意某些包不会将标志传递给 Electron，因此需要应用程序开发者来实现解决方案。

参见 Chromium#原生 Wayland 支持以了解在 Wayland 上工作的命令行标志。请注意，命令行标志 --ozone-platform-hint=auto 自 Electron 38 起已失效。

您可以手动传递这些标志，将它们保存在 Electron 配置文件中，或者覆盖应用程序的 ~/.local/share/applications 目录下的 .desktop 文件，方法是在 Exec= 行末尾添加标志。

本文或本章节的准确性存在争议。

原因: 旧版本的 Electron 需要 --enable-features=WebRTCPipeWireCapturer 但它是从哪个版本开始默认启用的？而且非自由软件打包的 Electron 的默认行为也会是错误的。（在 Talk:Wayland 中讨论）

Electron 默认启用通过 PipeWire 的 WebRTC 屏幕捕获。捕获基于 xdg-desktop-portal。

通过使用：--enable-features=WaylandWindowDecorations 可以解决顶部栏丢失的问题。这通常在 GNOME 下是必需的（自 electron17 起支持）。

环境变量

使用版本 28 到 37 之间的 Electron 的应用程序可以使用环境变量 ELECTRON_OZONE_PLATFORM_HINT 设置为 auto 或 wayland。

这比命令行标志的优先级低。

Java

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

参见 Debian:Wayland#Java 程序（自 OpenJDK 16 起支持？）

从 OpenJDK 16 开始，JRE 可以动态加载 GTK3（它具有 Wayland 支持），根据这个讨论，这似乎得到了支持。

可以将 _JAVA_AWT_WM_NONREPARENTING 环境变量设置为 "1" 来修复应用程序启动时出现空白屏幕的错误行为。

由于 XWayland 不具备与 Wayland 完全相同的功能，因此在 Wakefield 准备就绪之前，可以使用 WLToolkit 来填补这些空白。它可以通过 -Dawt.toolkit.name=WLToolkit 激活。某些程序，例如 JetBrains IDE 支持它。

技巧与提示

自动化

ydotool（ydotool）- 通用命令行自动化工具（不限于 wayland）。启用/启动 ydotool.service 用户单元。参见 ydotoold(8), ydotool(1)。
wtype（wtype）- Wayland 的 xdotool 输入。参见 wtype(1)。
keyboard - 适用于 Windows 和 Linux 的 Python 库，支持实验性的 OS X 支持。另请参阅 mouse 库。
wlrctl（wlrctl^AUR）- 用于各种 wlroots 扩展的命令行实用程序（支持 foreign-toplevel-management、virtual-keyboard、virtual-pointer）

重新映射键盘或鼠标按键

参见输入重映射实用程序。

屏幕录制

参见屏幕捕获#屏幕录制和屏幕捕获#使用 X11 应用程序录制 Wayland 窗口。

应用程序关闭后持久化剪贴板

本文档或本节可能是合并到剪贴板的候选。

注意: 即使在 Xorg 上，这也是标准行为。还有许多其他剪贴板管理器。（在 Talk:Wayland 中讨论）

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

将 Wayland 合成器作为 systemd 服务自启动

注意 Universal Wayland Session Manager 会自动为您的合成器生成 systemd 单元，此外它还有助于您将图形应用程序与 systemd 集成。

如果您不想使用显示管理器或 shell，可以将 Wayland 合成器与 systemd 服务一起自启动。使用您想使用的合成器调整 ExecStart 行。以下是 KDE Plasma 的示例

/etc/systemd/system/wayland-compositor.service

[Unit]
After=graphical.target systemd-user-sessions.service modprobe@drm.service
Conflicts=getty@tty1.service

[Service]
User=username
WorkingDirectory=~

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

StandardOutput=journal
ExecStart=/usr/lib/plasma-dbus-run-session-if-needed /usr/bin/startplasma-wayland

[Install]
WantedBy=graphical.target

为基于 wlroots 的合成器使用其他渲染器

对于基于 wlroots 的合成器，您可以通过指定 WLR_RENDERER 环境变量来使用其他 wlroots 渲染器，例如 vulkan。可用渲染器列表在 wlroots 文档中。

故障排除

色彩校正

参见背光#色彩校正。

慢动作、图形故障和崩溃

Gnome-shell 用户从 X 切换到 Wayland 时可能会遇到显示问题。根本原因之一可能是您为基于 Xorg 的 gnome-shell 设置了 CLUTTER_PAINT=disable-clipped-redraws:disable-culling。尝试从 /etc/environment 或其他 rc 文件中移除它，看看一切是否恢复正常。

远程显示

wlroots0.18 和 wlroots0.19（由 sway 使用）从 0.10 版本开始通过 wayvnc 提供了 VNC 后端。RDP 后端已被移除 [11]。
mutter 现在在编译时启用了远程桌面，详情请参阅 [12] 和 gnome-remote-desktop。
krfb 为 kwin 提供 VNC 服务器。krfb-virtualmonitor 可用于将另一个设备设置为附加显示器。
2013 年，FreeRDP 被合并到 Weston 中，并通过编译标志启用。自 6.0.0 版本起，weston 包已启用此功能。
waypipe（或 waypipe-git^AUR）是 Wayland 应用程序的透明代理，带有一个用于通过 SSH 运行的包装器命令。
- 以下是在 Plasma 中启动远程 KDE kcalc 的示例

$ waypipe ssh example.local env QT_QPA_PLATFORM=wayland QT_QPA_PLATFORMTHEME=KDE dbus-launch kcalc

游戏、远程桌面和虚拟机窗口中的输入抓取

与 Xorg 不同，Wayland 不允许独占输入设备抓取，也称为主动或显式抓取（例如键盘、鼠标），而是依赖 Wayland 合成器将键盘快捷键传递并将其指针设备限制在应用程序窗口内。

输入抓取的这种变化会破坏应用程序的当前行为，这意味着

合成器将捕获热键组合和修饰键，而不会将它们发送到远程桌面和虚拟机窗口。
鼠标指针将不会限制在应用程序的窗口内，这可能会导致视差效果，即虚拟机或远程桌面窗口内的鼠标指针位置与主机的鼠标指针不匹配。

Wayland 通过为 Wayland 和 Xwayland 添加协议扩展来解决此问题。需要将对这些扩展的支持添加到 Wayland 合成器中。对于原生 Wayland 客户端，使用的窗口小部件工具包（例如 GTK、Qt）需要支持这些扩展，或者应用程序本身需要支持（如果没有使用窗口小部件工具包）。对于 Xorg 应用程序，由于 Xwayland 支持已足够，因此应用程序或窗口小部件工具包无需更改。

这些扩展已包含在 wayland-protocols 中，并且受 xorg-xwayland 支持。

GTK 主题不起作用

请参阅 https://github.com/swaywm/sway/wiki/GTK-3-settings-on-Wayland。

避免加载 NVIDIA 模块

在启动 Sway 等 Wayland 合成器之前，将 __EGL_VENDOR_LIBRARY_FILENAMES=/usr/share/glvnd/egl_vendor.d/50_mesa.json 作为环境变量添加。

放大/表面缩放

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

Wayland 延迟/卡顿（内核 6.11.2 (AMD) 后）

在未来的内核版本中修补此问题之前，一种解决方法是将 amdgpu.dcdebugmask=0x400 添加到命令行参数中。

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

VRR/Vsync 开启时游戏/应用程序在失去焦点时挂起

本文章或章节需要扩充。

原因：如果找到，请在此处添加更多信息和指向相关上游文档的链接：该功能难以捉摸，并且似乎文档记录不佳。（在 Talk:Wayland 中讨论）

在切换工作区或使用 Alt+Tab 时，游戏（以及可能的其他图形应用程序）会被挂起，进入某种奇怪的状态，并且它们会（部分）停止。症状包括音频（部分）中断、游戏不进行、 ping 值急剧升高或网络中断，但这仅在游戏窗口失去焦点时发生。这可能仅影响 VSync 开启的应用程序。

一些游戏可以通过切换到窗口来解决此问题，但有些则不行。这对于需要大量使用网页浏览、文档和第三方工具的复杂游戏，或者如果游戏玩法因某种原因被打断，则会非常令人恼火。

可能的解决方法包括设置环境变量 MESA_VK_WSI_PRESENT_MODE=immediate 和/或 vk_xwayland_wait_ready=false，但设置这些将破坏任何 VSync 或 VRR 实现。

参见

在线 Wayland 文档
官方仓库
Fedora：如何调试 Wayland 问题
我们现在是 Wayland 了！ - "我们 Wayland 了吗？" 的更新版本
Awesome Wayland 项目
光标主题
Arch Linux 论坛讨论
i3 迁移指南 - i3 上常用的 X11 应用程序及其 Wayland 替代品
Wayland Explorer - 阅读 Wayland 文档的更好方式
如何判断应用程序是否正在使用 XWayland