Wayland

Wayland 是一个显示服务器协议，已普遍作为 X 窗口系统的继任者 [1] [2] [3] [4]。可参见 Wikipedia 上的 Wayland 与 Xorg 的对比。

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

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

系统需求

和 Xorg 不同的是，Wayland 本身只是一个协议，没有一个通用的“显示服务器”可供安装。需要安装的是兼容的 GPU 驱动（本节）和混成器（下一节）或将混成器内置其中的桌面环境（例如 GNOME 或 Plasma）。大多数 Wayland 混成器只能在使用内核级显示模式设置的系统上工作。

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

缓冲区 API	GPU 驱动支持	Wayland 混成器支持
GBM	除版本号低于 495 的 NVIDIA 驱动，均支持	全部
EGLStreams	NVIDIA	GNOME

* 版本 ≥ 495 的 NVIDIA 驱动同时支持 EGLStreams 和 GBM。[5]

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

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

GBM_BACKEND=nvidia-drm
__GLX_VENDOR_LIBRARY_NAME=nvidia

混成器

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

堆叠式

cosmic-comp — COSMIC 桌面环境的混成器。

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

hikari — 基于 wlroots 并受 cwm 启发开发，在 FreeBSD 上开发很活跃，但也支持 Linux。

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

KDE KWin — 请参阅 KDE#启动 Plasma。

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

labwc（英语：labwc） — 基于 wlroots 并受 Openbox 启发的混成器。

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

Mutter — 请参阅 GNOME#运行 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（英语：Window Maker）启发。

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

woodland — 一个极简轻量级的基于 wlroots 的堆叠式混成器，适用于 Wayland，受 wayfire 和 TinyWl 启发。

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

平铺式

Cagebreak（英语：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 — 功能齐全、可定制性强的平铺式 Xorg 窗口管理器和 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（英语：cwc） — 基于 wlroots、类似awesome的 Wayland 混成器

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

dwl（英语：dwl） — 基于 wlroots、类似 dwm 的 Wayland 混成器。

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

Hyprland — 不以牺牲外观为代价的动态平铺式 Wayland 混成器。

https://hypr.land || hyprland^包

japokwm — 基于 wlroots 创建布局的动态平铺式 Wayland 混成器。

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

Mangowc（英语：Mangowc） — 基于 dwl（英语：dwl）的混成器，提供标准配置文件、可选的滚动布局以及视觉特效支持。

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

river（英语：river） — 受 dwm 和 bspwm 启发的动态平铺式 Wayland 混成器。

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

其它

Cage — 像自助终端那样，全屏显示单个应用程序。

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

GNOME Kiosk — 基于 Mutter 的混成器，适用于固定用途或单应用部署，如墙面显示器和销售终端（kiosk）。

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/混成器.desktop 文件来了解如何启动显示上述混成器。

显示管理器

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

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

Xwayland

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

Xwayland 通过混成器启动，因此请参见所使用混成器的文档了解其兼容性和启动方式。

注意：

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

Wayback

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

NVIDIA 驱动

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

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

检测应用程序是否通过 Xwayland 运行

使用 xorg-xeyes^包的 xeyes 可以确定应用程序是否通过 Xwayland 运行，如果鼠标指针在 Xwayland 程序上，xeyes 窗口中的眼珠会转向鼠标指针。

或使用 xorg-xwininfo^包的 xwininfo。如果鼠标指针在 Xwayland 程序上，鼠标指针会变成“＋”。此时点击窗口，它会输出窗口信息并终止。

或使用 xorg-xlsclients^包的 xlsclients。运行 xlsclients -l 可列出所有正运行在 Xwayland 的应用程序。

或者也可以使用 extramaus^AUR。如果鼠标指针在 Xwayland 程序上，红色指针会随之移动。

提示：对于 KDE Plasma，还可以使用 KWin 调试控制台检查窗口。

图形库

GTK

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

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

Qt

要在 Qt 5 中启用 Wayland 支持，请安装 qt5-wayland^包。Qt 5 应用程序就会在 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]。

在某些混成器，例如sway，Qt 应用原生运行可能会有功能缺失。例如， KeepassXC 将无法最小化到托盘。在运行前安装qt5ct并设置QT_QPA_PLATFORMTHEME=qt5ct即可解决此问题。

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

Clutter

Clutter 工具包有 Wayland 后端支持，可以作为 Wayland 客户端运行。此后端支持已在 clutter^AUR 中启用。

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

SDL

在 SDL3 中，如果混成器支持 fifo-v1 协议，则默认使用 Wayland [9]。否则，会先尝试 X11。可以将 SDL_VIDEO_DRIVER 环境变量设置为 x11 或 wayland 来强制使用其一（或者，使用优先级较低的下述 SDL2 环境变量）[10]。

sdl2-compat^包遵循上述 SDL3 规则，但有特定应用程序的例外。至于 SDL2 本身（例如 sdl2^AUR），请设置 SDL_VIDEODRIVER=wayland。SDL_VIDEODRIVER="wayland,x11" 允许 SDL2 在 Wayland 不可用时使用 X11 [11]。可能还需要安装 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 变量的 X11 [12]

Electron

注意：在 Plasma 中，某些 Electron 应用程序可能在窗口上使用错误的图标（默认的 Wayland 图标），而在任务栏上使用正确的图标。使用特殊应用程序/窗口规则强制指定“桌面文件名”（即 .desktop 文件的文件名）可以绕过此问题。

使用命令行标志或环境变量可启用 Electron 的 Wayland 支持。

命令行标志

注意：某些应用程序不会将标志转发给 Electron，需要应用程序开发者提供解决方案。

关于启用 Electron Wayland 支持的命令行标志，请参见 Chromium#原生 Wayland 上运行。但需要注意，命令行标志 --ozone-platform-hint=auto 自 Electron 38 起已不再有效。

这些标志可以手动传递或#通过配置文件添加。通过编辑 .desktop 文件可以每次通过桌面项启动时传递。

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

原因： 旧版本的 Electron 需要 --enable-features=WebRTCPipeWireCapturer，但它从哪个版本开始默认启用？此外，非自由软件捆绑的 Electron 的默认行为可能是错误的。（在 en:Talk:Wayland 中讨论）

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

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

通过配置文件添加

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-desktop^AUR）来说，这些配置文件是无效的。不过在某些情况下也有替代品，如 slack-electron^AUR。

环境变量

使用 Electron 28 至 37 版本的应用程序可以使用环境变量 ELECTRON_OZONE_PLATFORM_HINT，将其设置为 auto 或 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 支持它）。

输入法

Fcitx 5

参见 Fcitx 5#Wayland。

IBus

参见 [13]。

提示与技巧

自动化

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

重新映射键盘或鼠标按键

参见输入重映射工具。

录制

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

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

本文或本章节可能需要合并到剪贴板。

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

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

将混成器作为 systemd 服务自动启动

提示：通用Wayland会话管理器可自动为混成器生成 systemd 单元，此外还可用于将图形应用程序与 systemd 集成。

如果不想使用显示管理器或 shell，可以通过 systemd 自动启动 Wayland 混成器。调整 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 文件中移除，即可查看是否一切恢复正常。

远程显示

sway 使用的wlroots0.18^包和wlroots0.19^包从 0.10 版本开始通过 wayvnc^包提供了一个 VNC 后端。RDP 后端则已被移除。[14]
目前 mutter^包在编译时就启用了远程桌面功能，详情请参阅 [15] 和 gnome-remote-desktop^包。
krfb^包为 kwin^包提供了一个 VNC 服务器。krfb-virtualmonitor 可用于将另一台设备设置为额外的显示器。
在 2013 年 Weston 合并了对 FreeRDP 的支持，可通过编译标志 (compile flag) 启用。weston^包自 6.0.0 版本开始启用了 FreeRDP。
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 客户端，其使用的部件工具集 (widget toolkits，比如 GTK，Qt) 需要支持这些插件；如果没有使用部件工具集，则需要支持应用程序本身。如果是 Xorg 应用程序，则不需要改变应用程序或者部件工具集，因为 Xwayland 的支持就足够了。

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

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

切换工作区/虚拟桌面时游戏/应用程序被挂起

这篇文章的某些内容需要扩充。

原因：如果找到，请在此处添加更多信息并引用上游文档：该功能难以捉摸且似乎文档记录不佳。 (在 en:Talk:Wayland 中讨论)

当切换工作区/虚拟桌面或使用 Alt+Tab 时，游戏（以及可能的其他图形应用程序）会被挂起，进入某种奇怪的状态，并（部分）停止运行。这包括 VRR 应用程序和开启了 VSync 的应用程序，但可能不仅限于此。症状包括音频（部分）中断、游戏无法进行、ping 大幅上升或掉线，但仅在游戏窗口未处于焦点时才会出现。

某些游戏可能可以通过切换到窗口模式来规避此问题，但有些则不行。这在需要大量使用网页浏览、文档和第三方工具的更复杂游戏中极其烦人，或者当游戏因某种原因被中断时也是如此。

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

另见

Wayland 在线文档（英文）
官方仓库（英文）
Fedora：如何排查 Wayland 问题（英文）
我们现在是 Wayland 了！（英文）- "Wayland 可用了吗？"的更新版本
Wayland 项目汇总（英文）
光标主题
Arch Linux 论坛讨论（英文）（页面将持续关注 Wayland 信息，如有兴趣请留意）
i3 迁移指南 - i3 上常用 X11 应用的 Wayland 替代品（英文）
Wayland Explorer - 阅读 Wayland 文档的更好方法（英文）
如何判断应用程序是否在使用 Xwayland（英文）