跳至內容

Wayland

出自 Arch Linux 中文维基

Wayland 是一個顯示伺服器協議,已普遍作為 X 窗口系統的繼任者 [1] [2] [3] [4]。可參見 Wikipedia 上的 Wayland 與 Xorg 的對比

由於使用 Wayland 協議的顯示伺服器也可作為混成窗口管理器,因此被稱為混成器(compositor)。你可以在#混成器中找到相關信息。

為了兼容原生 X11 應用程式,使其在 Wayland 中無縫運行,可以使用 #Xwayland,它在 Wayland 中提供了 X 伺服器。

系統需求

Xorg 不同的是,Wayland 本身只是一個協議,沒有一個通用的「顯示伺服器」可供安裝。需要安裝的是兼容的 GPU 驅動(本節)和混成器(下一節)或將混成器內置其中的桌面環境(例如 GNOMEPlasma)。大多數 Wayland 混成器只能在使用內核級顯示模式設置的系統上工作。

GPU 驅動與 Wayland 混成器必須支持相同的緩衝區 API (Buffer API) 才能夠互相兼容。現在主要有兩種 API:GBMEGLStreams

緩衝區 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-compCOSMIC 桌面環境的混成器。
https://github.com/pop-os/cosmic-comp || cosmic-comp
  • hikari — 基於 wlroots 並受 cwm 啟發開發,在 FreeBSD 上開發很活躍,但也支持 Linux。
https://hikari.acmelabs.space/ || hikariAUR
https://userbase.kde.org/KWin || kwin
  • labwc英語labwc — 基於 wlroots 並受 Openbox 啟發的混成器。
https://github.com/labwc/labwc || labwc
https://gitlab.gnome.org/GNOME/mutter || mutter
  • waybox — 一個 *box 風格(極簡主義)的 Wayland 混成器,主要基於 Openbox 設計。
https://github.com/wizbright/waybox || wayboxAUR
  • 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://phkaeser.github.io/wlmaker/ || wlmakerAUR
  • woodland — 一個極簡輕量級的基於 wlroots 的堆疊式混成器,適用於 Wayland,受 wayfire 和 TinyWl 啟發。
https://github.com/DiogenesN/woodland || woodlandAUR

平鋪式

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 — 功能齊全、可定製性強的平鋪式 Xorg 窗口管理器和 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

動態

  • cwc英語cwc — 基於 wlroots、類似awesome的 Wayland 混成器
https://cudiph.github.io/cwc/apidoc/ || cwcAUR
  • dwl英語dwl — 基於 wlroots、類似 dwm 的 Wayland 混成器。
https://codeberg.org/dwl/dwl || dwlAUR
  • Hyprland — 不以犧牲外觀為代價的動態平鋪式 Wayland 混成器。
https://hypr.land || hyprland
  • japokwm — 基於 wlroots 創建布局的動態平鋪式 Wayland 混成器。
https://github.com/werererer/japokwm || japokwm-gitAUR
  • Mangowc英語Mangowc — 基於 dwl英語dwl 的混成器,提供標準配置文件、可選的滾動布局以及視覺特效支持。
https://github.com/DreamMaoMao/mangowc || mangowcAUR
  • 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-kioskAUR
  • phoc — 適用於行動裝置的基於 wlroots 的輕量混成器。
https://gitlab.gnome.org/World/Phosh/phoc || phoc
  • Wayback — X11 兼容層,允許使用 Wayland 組件運行完整的 X11 桌面環境。實驗性,開發處於早期階段。
https://wayback.freedesktop.org/ || wayback-x11AUR

上述某些混成器支持從顯示管理器啟動。請查看 /usr/share/wayland-sessions/混成器.desktop 文件來了解如何啟動顯示上述混成器。

顯示管理器

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

名稱 運行於 描述
emptty tty 簡單的 TTY CLI 顯示管理器。
plasma-login-manager-gitAUR Wayland KDE目前正在活躍開發的顯示管理器。
GDM Wayland GNOME 的顯示管理器。
greetd Wayland/Xorg/tty

參考 Greetd#Greeters

極簡且使用靈活的登錄守護程序。
lemurs tty 用 Rust 編寫的 TUI 顯示管理器。
lidmAUR tty 用C語言開發的全彩可定製的TUI 顯示管理器.
LightDM Xorg[6] 跨桌面顯示管理器。
ly tty 用 Zig 語言編寫的 TUI 顯示管理器。
SDDM Wayland/Xorg 基於 QML 開發的顯示管理器。
tbsmAUR 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

Waybackwayback-x11AURwayback-x11-gitAUR)是一個 X11 兼容層,允許使用 Wayland 組件運行完整的 X11 桌面環境,旨在最終取代 Xorg,從而減輕 X11 應用程式的維護負擔。

NVIDIA 驅動

注意:470 版本之前的 NVIDIA 驅動(例如 nvidia-390xx-dkmsAUR)不支持硬體加速的 Xwayland,導致非 Wayland 原生應用程式在 Wayland 會話中性能不佳。

需要啟用 DRM KMS。有關您的顯示管理器(例如 GDM)的更多信息,請參閱官方文檔

檢測應用程式是否通過 Xwayland 運行

使用 xorg-xeyesxeyes 可以確定應用程式是否通過 Xwayland 運行,如果滑鼠指針在 Xwayland 程序上,xeyes 窗口中的眼珠會轉向滑鼠指針。

或使用 xorg-xwininfoxwininfo。如果滑鼠指針在 Xwayland 程序上,滑鼠指針會變成「+」。此時點擊窗口,它會輸出窗口信息並終止。

或使用 xorg-xlsclientsxlsclients。運行 xlsclients -l 可列出所有正運行在 Xwayland 的應用程式。

或者也可以使用 extramausAUR。如果滑鼠指針在 Xwayland 程序上,紅色指針會隨之移動。

提示:對於 KDE Plasma,還可以使用 KWin 調試控制台檢查窗口。

圖形庫

GTK

gtk3gtk4 包已經提供了 Wayland 支持。GTK 默認使用 Wayland 後端,但是可以通過修改環境變量為 GDK_BACKEND=x11 覆蓋默認設置切換到 Xwayland。

關於主題問題,請參閱 GTK#Wayland_後端

Qt

要在 Qt 5 中啟用 Wayland 支持,請安裝 qt5-wayland。Qt 5 應用程式就會在 Wayland 會話下運行。

雖然通常不需要,但若要顯式使用 Wayland 插件運行 Qt 應用程式 [7],請使用 -platform waylandQT_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 客戶端運行。此後端支持已在 clutterAUR 中啟用。

要在 Wayland 上運行 Clutter 應用,請設置 CLUTTER_BACKEND=wayland 環境變量。

SDL

SDL3 中,如果混成器支持 fifo-v1 協議,則默認使用 Wayland [9]。否則,會先嘗試 X11。可以將 SDL_VIDEO_DRIVER 環境變量設置為 x11wayland 來強制使用其一(或者,使用優先級較低的下述 SDL2 環境變量)[10]

sdl2-compat 遵循上述 SDL3 規則,但有特定應用程式的例外。至於 SDL2 本身(例如 sdl2AUR),請設置 SDL_VIDEODRIVER=waylandSDL_VIDEODRIVER="wayland,x11" 允許 SDL2 在 Wayland 不可用時使用 X11 [11]。可能還需要安裝 libdecor 才能啟用窗口裝飾(例如在 GNOME 上)。

參見官方說明

GLFW

glfw 支持 Wayland,如果環境變量 XDG_SESSION_TYPE 設置為 wayland,並且應用程式開發人員沒有設置特定的後端,則使用 Wayland 後端。

查看原始碼以獲取更多信息。

GLEW

如果 glew-wayland-gitAUR 包無法與所需的 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.confXX 為 Electron 版本號)文件添加到命令行參數(一行一個),如果版本特定的文件不存在,則回退到全版本的 ~/.config/electron-flags.conf

例如,將上述參數寫入共享配置文件:

~/.config/electron-flags.conf
--enable-features=WaylandWindowDecorations
--ozone-platform-hint=auto
注意:這些配置文件僅對官方倉庫的 Electron 軟體包和使用這些 Electron 包的應用程式有效。對於自帶 Electron 的軟體包(如 slack-desktopAUR)來說,這些配置文件是無效的。不過在某些情況下也有替代品,如 slack-electronAUR

環境變量

使用 Electron 28 至 37 版本的應用程式可以使用環境變量 ELECTRON_OZONE_PLATFORM_HINT,將其設置為 autowayland

如果同時指定,命令行標誌優先。

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 激活。一些程序支持它。

輸入法

Fcitx 5

參見 Fcitx 5#Wayland

IBus

參見 [13]

提示與技巧

自動化

重新映射鍵盤或滑鼠按鍵

參見輸入重映射工具

錄製

參見屏幕捕獲#屏幕錄製屏幕捕獲#通過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.18wlroots0.19 從 0.10 版本開始通過 wayvnc 提供了一個 VNC 後端。RDP 後端則已被移除。[14]
  • 目前 mutter 在編譯時就啟用了遠程桌面功能,詳情請參閱 [15]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 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

切換工作區/虛擬桌面時遊戲/應用程式被掛起

這篇文章的某些內容需要擴充。

原因:如果找到,請在此處添加更多信息並引用上游文檔:該功能難以捉摸且似乎文檔記錄不佳。 (在 en:Talk:Wayland 中討論)

當切換工作區/虛擬桌面或使用 Alt+Tab 時,遊戲(以及可能的其他圖形應用程式)會被掛起,進入某種奇怪的狀態,並(部分)停止運行。這包括 VRR 應用程式和開啟了 VSync 的應用程式,但可能不僅限於此。症狀包括音頻(部分)中斷、遊戲無法進行、ping 大幅上升或掉線,但僅在遊戲窗口未處於焦點時才會出現。

某些遊戲可能可以通過切換到窗口模式來規避此問題,但有些則不行。這在需要大量使用網頁瀏覽、文檔和第三方工具的更複雜遊戲中極其煩人,或者當遊戲因某種原因被中斷時也是如此。

可能的解決方法包括設置環境變量 MESA_VK_WSI_PRESENT_MODE=immediate 和/或 vk_xwayland_wait_ready=false,但設置這些會破壞所有 VSync 或 VRR 實現。

另見