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://codeberg.org/dwl/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)