Wayland

翻译状态：

• 本文（或部分内容）是 Wayland 的翻译，最近一次同步的日期是 2023-03-13，如果英文版本有所更改，则您可以帮助同步翻译更改的内容。
• 您可以在ArchWiki 的对应页面找到本文翻译的原始编辑记录和贡献者列表。

相关文章

• 内核级显示模式设置
• Xorg
• 屏幕捕获#Wayland

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

由于使用 Wayland 协议的显示服务器也可作为混成窗口管理器，因此被称为混成器（compositors）。

XWayland 在 Wayland 中提供了 X 服务器，可以让 X11 应用程序无缝运行于 Wayland 中。

系统需求

目前 Wayland 只能在使用了 KMS 的系统上工作。Wayland 本身并不提供图形环境；为此还需要安装混成器，或者内置混成器的桌面环境，比如 GNOME 或 KDE。

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

缓冲区 API	GPU 驱动支持	Wayland 混成器支持
GBM	除版本号低于 495 的 NVIDIA 驱动，均支持	全部
EGLStreams	NVIDIA	GNOME, KDE, Weston（需要第三方补丁）

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

自 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

注意在错误的环境下设置此变量可能导致火狐浏览器崩溃等问题。

混成器

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

平铺式

• Cagebreak — 基于 cage，受 Ratpoison 启发。

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

• Cardboard — 受 PaperWM 启发、基于 wlroots 的滚动混成器。

https://gitlab.com/cardboardwm/cardboard || cardboard-git^AUR

• dwl — 基于 wlroots、类似 dwm 的 Wayland 混成器。

https://github.com/djpohly/dwl || dwl^AUR

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

https://github.com/hyprwm/Hyprland || hyprland^包

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

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

• newm — 适合笔记本电脑和触摸板用户的 Wayland 混成器。

https://github.com/jbuchermn/newm/ || newm-git^AUR

• Qtile — 功能齐全、可定制性强的平铺式窗口管理器和 Wayland 混成器，使用 Python 开发、配置。

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

• river — 受 dwm 和 bspwm 启发的动态平铺 Wayland 混成器。

https://github.com/ifreund/river || river^AUR

• Sway — 基于 wlroots、与 i3 兼容的 Wayland 混成器。

https://github.com/swaywm/sway || sway^包

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

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

• Vivarium — 使用 wlroots 的动态平铺 Wayland 混成器，桌面部分受 xanmod 启发。

https://github.com/inclement/vivarium || vivarium-git^AUR

• waymonad — 受 xmonad 启发、用 Haskell 编写的 Wayland 混成器。

https://github.com/waymonad/waymonad || not packaged? search in AUR

堆叠式

• Enlightenment — 请参阅 Enlightenment#Manually。更多信息：[1]^{[失效链接 2022-09-23 ⓘ]} [2]

https://www.enlightenment.org/ || enlightenment^包

• Greenfield — 一款可以在网页浏览器中运行、并显示远程应用的 Wayland 混成器。

https://greenfield.app/ ||

• Grefsen — 一款提供最精简桌面环境的 Qt/Wayland 混成器。

https://github.com/ec1oud/grefsen ||

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

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

• KDE KWin — 请参阅 KDE#Starting Plasma。

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

• Liri Shell — Liri 一部分，其使用 QtQuick 和 QtCompositor 为 Wayland 构建。

https://github.com/lirios/shell || liri-shell-git^AUR

• labwc — 受 Openbox 启发，基于 wlroots 的混成器.

https://github.com/labwc/labwc || labwc-git^AUR

• Mutter — 请参阅 GNOME#Starting。

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

• Orbital — 一款使用 Qt5 和 Weston 的混成器和 Shell（它更像是窗户管理器而非桌面环境）。目标是构建一个简单但灵活且美观的桌面。

https://github.com/giucam/orbital ||

• wayfire — 3D 混成器，受 Compiz 启发并基于 wlroots 开发。

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

• Weston — 本身还是其它 Wayland 混成器开发的实现参考。

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

• wio — 一款基于 wlroots 的混成器，致力于复刻 Plan 9 的 Rio 桌面的外观和质感。

https://wio-project.org/^{[失效链接 2022-09-23 ⓘ]} ||

其它类型

• Cage — 显示单个全屏应用程序（就像自助取款机那样）。

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

• Maze Compositor — 使用 Qt 将窗口渲染成 3D 迷宫一样。

https://github.com/imbavirus/mazecompositor ||

• Motorcar — 一款使用虚拟现实来探索 3D 窗口的 Wayland 混成器。

https://github.com/evil0sheep/motorcar ||

• nwg-shell — 基于 GTK 的 Shell (适用于 sway Wayland 混成器) 。

https://github.com/nwg-piotr/nwg-shell || nwg-shell^AUR

• kiwmi — 完全可编程的 Wayland 混成器。

https://github.com/buffet/kiwmi || kiwmi-git^AUR

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

显示管理器

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

名称	在 Wayland 上运行	描述
GDM	是	GNOME 的显示管理器。
greetd	提供了 Wayland 登录程序	极简且使用灵活的登录守护程序。
LightDM	否	跨桌面显示管理器。
Ly	否	用 C 语言编写的 TUI 显示管理器。
SDDM	是	基于 QML 开发的显示管理器。
tbsm	否	用纯 Bash 编写的简单 CLI 会话启动器。

图形库

详情请查看 官方网站。

GTK

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

Qt 5

要在 Qt 5 和 6 中启用 Wayland 支持，请按需安装 qt5-wayland^包、qt6-wayland^包 软件包。

要使用 Wayland 插件运行 Qt 5 应用程序[3]，请使用 -platform wayland 或 QT_QPA_PLATFORM=wayland 环境变量；要强制在 Wayland 会话中使用 X11，则使用 QT_QPA_PLATFORM=xcb。后者对于某些不使用系统 Qt 实现的应用（比如 zoom^AUR），可能是必需的。QT_QPA_PLATFORM="wayland;xcb" 让 Qt 在 Wayland 不可用时使用 xcb (X11) 插件[4]。

对于诸如 sway 的一些混成器，在运行 Qt 程序时可能会遇到一些功能缺失。例如，KeepassXC 会无法最小化到托盘。通过安装 qt5ct^包 并在程序运行前设置好 QT_QPA_PLATFORMTHEME=qt5ct 环境变量，可以解决此问题。

Clutter

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

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

SDL

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

注意： 很多专有游戏集成了旧版本的 SDL，导致并不支持 Wayland，而且如果设置了 SDL_VIDEODRIVER=wayland 环境变量还可能会导致游戏完全无法运行。要强制应用在 XWayland 上运行，请设置 SDL_VIDEODRIVER=x11 环境变量。

GLFW

要在 Wayland 后端上使用 GLFW，请安装 glfw-wayland^包 软件包（而不是 glfw-x11^包）。

GLEW

glew-wayland^AUR 软件包支持的后端还很少，请使用 glew^包 和 Xwayland. FS#62713。

EFL

EFL 已经完全支持 Wayland。要在 Wayland 上运行 EFL 应用，请参阅 Wayland 项目页面。

winit

Winit 是 Rust 语言中的窗口处理库。其默认使用 Wayland 后端，但是可以通过修改环境变量为 WINIT_UNIX_BACKEND=x11 覆盖设置将其切换到 Xwayland。

Electron

为每个应用单独添加命令行参数或者编写全局配置文件，可以为 Electron 应用添加 Wayland 支持。

命令行参数

为了让基于 electron^包 的应用在 Wayland 下运行，必须添加这些命令行参数 (例如 Electron 20 中): --ozone-platform-hint=auto.

如果运行时发现应用没有标题栏，请将上述参数修改为 --enable-features=WaylandWindowDecorations。此特性从 electron17 开始支持，且对于 GNOME 尤其必要。

一个技巧是将命令行参数添加到 .desktop 文件中 并将上述命令行参数添加到 Exec= 行的末尾。

警告： 诸如 visual-studio-code-bin^AUR (bug report) 的一些应用在启动时不会将命令行参数传递给 Electron，此问题需要由应用的开发者才能解决。

配置文件

新建或修改 ${XDG_CONFIG_HOME}/electron-flags.conf (默认是 .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

注意： 旧版本的 Electron 需要单独设置 electron<version>-flags.conf 文件，创建到 ${XDG_CONFIG_HOME}/electron-flags.conf 的符号链接是比较推荐的做法。

旧版本 Electron 需要的参数也不同，例如 Electron 13 需要:

~/.config/electron13-flags.conf

--enable-features=UseOzonePlatform
--ozone-platform=wayland

对于中文用户

KDE Plasma 5.27 合并了 text-input-v1。在 5.27 及以上版本的 KDE Plasma 中，通过启动 Electron 应用程序时添加 --enable-wayland-ime，可以在 Wayland 下使用中文输入法。

对于其他桌面环境/混成器，Electron 运行在 Wayland 下时不能使用中文输入法（包括 Fcitx5、ibus 等）输入文字，关于此问题另见此 GitHub Issue。

Java

Java 平台的开源实现 OpenJDK 尚未原生支持 Wayland。

Wakefield 是一个以在 OpenJDK 中实现 Wayland 为目标的项目。在此项目可用之前，可以使用 XWayland。

XWayland

XWayland 是一个运行在 Wayland 之下的 X 服务器，为尚未提供Wayland支持的本地 X11 应用程序提供兼容性。要使用 XWayland，请安装 xorg-xwayland 软件包。

XWayland 通过混成器启动，因此需要查阅所选混成器的文档以了解 XWayland 的兼容性以及有关如何启动 XWayland 的说明。

注意：

• 安全性：XWayland 是一个 X 服务器，因此它不具备 Wayland 的安全特性
• 性能：XWayland 的 性能几乎与 X11 相同。在某些情况下，可能会有肉眼可见的性能下降，尤其是在 NVIDIA 显卡上。
• 兼容性：XWayland 不完全向后兼容 X11。 某些应用程序可能无法在 XWayland 下正常运行。

NVIDIA 驱动程序

注意： 版本低于 470 的 NVIDIA 驱动程序 (例如 nvidia-390xx-dkms^AUR) 在 XWayland 下不支持硬件加速，导致非 Wayland 本地应用程序在 Wayland 会话中性能不佳。

需要启用 DRM KMS。官方文档中可能有关于您的显示管理器（例如 GDM）的其他信息。

提示与技巧

自动化

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

KWin Wayland 调试控制台

如果您在使用 kwin^包，执行以下命令即可查看哪些窗口使用 XWayland，哪些窗口使用原生 Wayland 的显示面 (surface) 、输入事件、剪贴板内容等等。

$ qdbus org.kde.KWin /KWin org.kde.KWin.showDebugConsole

直观地检测 XWayland 应用程序

可以通过运行 extramaus^AUR 来判断应用程序是否通过 XWayland 运行。

请将鼠标指针移动到应用程序的窗口上。如果红色光标移动，说明该应用程序正在通过 XWayland 运行。

除此之外也可以使用 xorg-xeyes^包 来检测。当鼠标指针移动到应用程序的窗口上时，注意观察眼睛是否发生移动。

还可以通过在终端里运行 xwininfo (需要事先安装 xorg-xwininfo^包)：当光标悬停在 XWayland 窗口上时，鼠标指针将变成加号 (+) 。如果点击该窗口，终端里会显示一些信息，但对于原生 Wayland 窗口则什么都不会发生。使用 Ctrl+C 可以终止此程序。

重新映射键盘或鼠标按键

参见 Input remap utilities。

故障排除

颜色校正

请参阅背光#色彩校正。

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

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

远程显示

• sway 使用的 wlroots^包 从 0.10 版本开始通过 wayvnc^包 提供了一个 VNC 后端。RDP 后端则已被移除。 [5].
• 目前 mutter^包 在编译时就启用了远程桌面功能，详情请参阅 [6] 和 gnome-remote-desktop^包。
• 在 2013 年 Weston 合并了对 FreeRDP 的支持，可通过编译标志 (compile flag) 启用。weston^包 自 6.0.0 版本开始启用了 FreeRDP。
• waypipe^AUR (或 waypipe-git^AUR) 是适用于 Wayland 应用的透明代理，可通过封装的命令在 SSH 上运行。

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

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

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

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

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

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

相关的扩展有：

• XWayland 键盘捕获协议
• 混成器快捷键禁止协议
• 相对指针协议
• 指针约束协议

支持的 Wayland 混成器有：

• Mutter，GNOME 的混成器 (窗口管理器) ，从 3.28 版本开始支持
• wlroots 支持相对指针协议和指针约束协议

支持的部件工具集有：

• 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 添加到系统环境变量中。

另请参阅

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