Wayland 是一個旨在替代 X 窗口系統的顯示伺服器協議。此處有 Wayland 和 Xorg 的對比。
由於使用 Wayland 協議的顯示伺服器也可作為混成窗口管理器,因此被稱為混成器(compositors)。你可以在#混成器中找到相關信息。
為了兼容原生 X11 應用程式,使其在 Wayland 中無縫運行,可以使用 #Xwayland,它在 Wayland 中提供了 X 伺服器。
系統需求
大多數 Wayland 混成器只能在使用了 Kernel mode setting 的系統上工作。Wayland 本身並不提供圖形環境;為此還需要安裝混成器(參見下一節),或者內置混成器的桌面環境,比如 GNOME 或 Plasma。
GPU 驅動程序與 Wayland 混成器必須支持相同的緩衝區 API (Buffer API) 才能夠互相兼容。現在主要有兩種 API:GBM 和 EGLStreams。
緩衝區 API | GPU 驅動支持 | Wayland 混成器支持 |
---|---|---|
GBM | 除版本號低於 495 的 NVIDIA 驅動,均支持 | 全部 |
EGLStreams | NVIDIA | GNOME |
- * 版本 ≥ 495 的 NVIDIA 驅動同時支持 EGLStreams 和 GBM。[1]
自 NVIDIA 在版本 495 引入 GBM 支持以來,許多合成器 (包括 Mutter 和 KWin) 都開始默認使用 GBM 。通常認為 GBM 更好,有更為廣泛的支持,而以前僅支持 EGLStreams 是因為之前無法在 Wayland 下通過專有驅動程序來使用 NVIDIA GPU。此外,在 NVIDIA 支持 GBM 後,KWin 放棄了對 EGLStreams 的支持[2]。
如果您使用的是流行的桌面環境/混成器,GPU 也受 NVIDIA 支持,那麼很可能已經在使用 GBM 後端了。要檢查是否使用 GBM 後端,請執行 journalctl -b 0 --grep "renderer for"
。要強制使用 GBM 後端,請設置以下環境變量:
GBM_BACKEND=nvidia-drm __GLX_VENDOR_LIBRARY_NAME=nvidia
混成器
堆疊式、平鋪式和動態的區別參見窗口管理器#類型。
堆疊式
- Enlightenment — 請參閱 Enlightenment#Manually。更多信息:[3] [4]
- hikari — 基於 wlroots 並受 cwm 啟發開發,在 FreeBSD 上開發很活躍,但也支持 Linux。
- KDE KWin — 請參閱 KDE#Starting Plasma。
- Liri Shell — Liri 一部分,其使用 QtQuick 和 QtCompositor 為 Wayland 構建。
- labwc — 基於 wlroots 並受 Openbox 啟發的混成器。
- Mutter — 請參閱 GNOME#Starting。
- wayfire — 3D 混成器,受 Compiz 啟發並基於 wlroots 開發。
- https://wayfire.org/ || wayfireAUR
- Weston — Wayland 混成器,設計注重正確性、可靠性、可預測性和性能。
- wio — 基於 wlroots 的混成器,致力於復刻 Plan 9 的 Rio 桌面的外觀和質感。
平鋪式
- miracle-wm — 基於 Mir 的 Wayland 混成器,風格類似 i3 和 sway,旨在比兩者更炫目且功能更豐富,如 swayfx。
- niri — 可滾動的平鋪式 Wayland 混成器。
- Qtile — 功能齊全、可定製性強的平鋪式窗口管理器和 Wayland 混成器,使用 Python 開發、配置。
- SwayFx — Sway,但帶有視覺效果!
- Velox — 基於 swc 的簡單窗口管理器,受 dwm 和 xmonad 啟發。
動態
- Hyprland — 不以犧牲外觀為代價的動態 Wayland 平鋪混成器。
- japokwm — 基於 wlroots 創建布局的動態 Wayland 平鋪混成器。
- Vivarium — 使用 wlroots 的動態平鋪 Wayland 混成器,桌面部分受 xanmod 啟發。
其它類型
- Cage — 顯示單個全屏應用程式(就像自助取款機那樣)。
- phoc — 適用於行動裝置的基於 wlroots 的輕量混成器。
上述某些混成器/窗口管理器支持顯示管理器。請查看 /usr/share/wayland-sessions/compositor.desktop
文件來了解如何啟動顯示上述混成器/窗口管理器。
顯示管理器
下面列出的顯示管理器均支持啟動 Wayland 混成器。
名稱 | 在 Wayland 上運行 | 描述 |
---|---|---|
emptty包 | 否 | 簡單的 TTY CLI 顯示管理器。 |
GDM | 是 | GNOME 的顯示管理器。 |
greetd | 使用 Wayland 登錄程序時 | 極簡且使用靈活的登錄守護程序。 |
lemurs包 | 否 | 用 Rust 編寫的 TUI 顯示管理器。 |
LightDM | 否 | 跨桌面顯示管理器。 |
ly包 | 否 | 用 C 語言編寫的 TUI 顯示管理器。 |
SDDM | 是 | 基於 QML 開發的顯示管理器。 |
tbsmAUR | 否 | 用純 Bash 編寫的簡單 CLI 會話啟動器。 |
uwsm | 否 | 利用 Systemd 機制的獨立混成器會話和 XDG 自動啟動管理器。 |
Xwayland
Xwayland(1) 是一個在 Wayland 下運行的 X 伺服器,為尚未提供 Wayland 支持的原生 X11 應用程式提供兼容性。要使用它,請 安裝 xorg-xwayland包 包。
Xwayland 通過合成器啟動,因此您應查看所選合成器的文檔,以了解 Xwayland 的兼容性以及如何啟動 Xwayland。
- 安全性:Xwayland 是一個 X 伺服器,因此它不具備 Wayland 的安全特性。
- 性能:Xwayland 的性能與 X11 幾乎相同。在某些情況下,您可能會注意到性能下降,尤其是在 NVIDIA 顯卡上。
- 兼容性:Xwayland 並不完全向後兼容 X11。某些應用程式在 Xwayland 下可能無法正常工作。
NVIDIA 驅動
需要啟用 DRM KMS。有關您的顯示管理器(例如 GDM)的更多信息,請參閱 官方文檔。
Kwin Wayland 調試控制台
如果您使用 kwin包,可以執行以下命令來查看哪些窗口使用 Xwayland 或原生 Wayland、表面、輸入事件、剪貼板內容等。
$ qdbus6 org.kde.KWin /KWin org.kde.KWin.showDebugConsole
視覺上檢測 Xwayland 應用程式
要確定應用程式是否通過 Xwayland 運行,您可以運行 extramausAUR。 將滑鼠指針移動到應用程式的窗口上。如果紅色滑鼠移動,則應用程式通過 Xwayland 運行。
或者,您可以使用 xorg-xeyes包,看看當滑鼠指針移動到應用程式窗口上時,眼睛是否在移動。
另一個選項是在終端窗口中運行 xwininfo(來自 xorg-xwininfo包):當懸停在 Xwayland 窗口上時,滑鼠指針會變成 + 號。如果您點擊窗口,它將顯示一些信息並結束,但對於原生 Wayland 窗口則不會執行任何操作。您可以使用 Ctrl+C
來結束它。
您還可以使用 xlsclients(來自 xorg-xlsclients包 包)。要列出所有通過 Xwayland 運行的應用程式,請運行 xlsclients -l
。
圖形庫
GTK
gtk3包 和 gtk4包 包已經提供了 Wayland 支持。GTK 默認使用 Wayland 後端,但是可以通過修改環境變量為 GDK_BACKEND=x11
覆蓋默認設置切換到 XWayland。
關於主題問題,請參閱 GTK#Wayland_後端。
Qt
要在 Qt 5 或 6 中啟用 Wayland 支持,請分別安裝 qt5-wayland包 或 qt6-wayland包 軟體包。Qt 應用程式將在 Wayland 會話下運行。
雖然通常不需要,但若要顯式使用 Wayland 插件運行 Qt 應用程式 [5],請使用 -platform wayland
或 QT_QPA_PLATFORM=wayland
環境變量。
要在 Wayland 會話中強制使用 X11,請使用 QT_QPA_PLATFORM=xcb
。這對於某些不使用系統 Qt 實現的應用(比如 zoomAUR)可能是必需的。QT_QPA_PLATFORM="wayland;xcb"
允許 Qt 在 Wayland 不可用時使用 xcb (X11) 插件 [6]。
由於 Qt WebEngine 在 Wayland 上使用分數縮放時出現錯誤尺寸和文本渲染問題 的 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 視頻驅動 [7]。你可能還需要安裝 libdecor包 以啟用窗口裝飾(例如在 GNOME 上)。
參見官方說明。
GLFW
glfw包 包支持 Wayland,如果 環境變量 XDG_SESSION_TYPE
設置為 wayland
,並且應用程式開發人員沒有設置特定的後端,則使用 Wayland 後端。
查看 原始碼 以獲取更多信息。
GLEW
如果 glew-wayland-gitAUR 包無法與所需的 GLEW 應用程式一起使用,則可以使用 glew包 和 Xwayland。參見 FS#62713。
EFL
EFL 已經完全支持 Wayland。要在 Wayland 上運行 EFL 應用,請參閱 Wayland 項目頁面[失效連結 2024-10-12 ⓘ]。
winit
Winit 是 Rust 語言中的窗口處理庫。默認使用 Wayland 後端,但可以通過修改環境變量將其切換到 Xwayland:
- 在 0.29.2 版本之前,設置
WINIT_UNIX_BACKEND=x11
- 對於 0.29.2 及更高版本,取消設置
WAYLAND_DISPLAY
,這將強制回退到使用DISPLAY
變量的 X [8]
Electron
可以通過為每個應用程式單獨添加命令行參數或使用配置文件來激活 Wayland 支持。詳情請參閱 #配置文件。
要確定應用程式使用的 Electron 版本,請參閱 [9]。
環境變量
使用 Electron 28 及更高版本的應用程式可以使用 環境變量 ELECTRON_OZONE_PLATFORM_HINT 設置為 auto
或 wayland
。
此設置的優先級低於命令行參數。
命令行參數
與基於 Chromium 的 Electron 不同,Electron 應用程式默認不啟用基於 PipeWire 的 WebRTC 屏幕捕獲。因此,建議使用 --enable-features=WebRTCPipeWireCapturer
以避免在 Wayland 上出現屏幕捕獲問題。捕獲基於 xdg-desktop-portal包。
要在 Wayland 上原生使用 electron包 應用程式,當使用環境變量不可行或不理想時,可以在 Electron 20+ 中添加 --ozone-platform-hint=auto
。
缺少頂部欄的問題可以通過使用 --enable-features=WaylandWindowDecorations
解決。這在 GNOME 下通常是必要的(自 electron17 開始支持)。
你可以通過 修改 .desktop 文件 並將這些參數添加到 Exec=
行的末尾來更永久地設置這些參數,或者更乾淨地使用下面描述的配置文件。
配置文件
Electron 軟體包讀取 ~/.config/electronXX-flags.conf
文件,其中 XX 是 Electron 版本,如果版本文件不存在,則回退到共享的 ~/.config/electron-flags.conf
。
將上述參數每行一個地放入文件中:
~/.config/electron-flags.conf
--enable-features=WaylandWindowDecorations --ozone-platform-hint=auto
舊版本 Electron
electron25-flags.conf
僅適用於 Electron 25 版本。舊版本的 Electron 可以使用各自的 electron<version>-flags.conf
文件進行配置。
舊版本可能需要不同的參數,具體取決於相應的 Chromium 版本。例如,以下參數適用於 Electron 13:
~/.config/electron13-flags.conf
--enable-features=UseOzonePlatform --ozone-platform=wayland
無法使用fcitx5輸入法
在支持text_input_v1
協議的合成器上,你可以嘗試添加--enable-wayland-ime
標示。
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 支持它)。
提示與技巧
自動化
-
ydotool (ydotool包) - 通用的命令行自動化工具 (不限於 Wayland)。啟用/啟動
ydotool.service
用戶單元。參見 ydotoold(8),ydotool(1)。 - wtype (wtype包) - 適用 Wayland 的 xdotool type。參見 wtype(1)。
- keyboard - 可在 Windows 和 Linux 上穩定工作、實驗性支持 OS X 的 Python 庫。另請參見滑鼠 (mouse) 庫。
- wlrctl (wlrctlAUR) - 用於各種 wlroots 擴展的命令行工具(支持 foreign-toplevel-management、virtual-keyboard、virtual-pointer)。
重新映射鍵盤或滑鼠按鍵
參見 輸入重映射工具。
使用 X11 應用程式錄製 Wayland 窗口
參見 屏幕捕獲#通過_X11_應用程式投射_Wayland_屏幕。
Chromium 無法完全最大化
您需要通過 chrome://settings/appearance 菜單啟用 使用系統標題欄和邊框。
應用程式關閉後保留剪貼板內容
由於 Wayland 的設計理念,剪貼板數據存儲在源客戶端的內存中。當客戶端關閉時,剪貼板數據將丟失。您可以使用 wl-clip-persist包 來解決這個問題,它在後台運行以讀取剪貼板數據並將其存儲在自己的內存中,與源客戶端分離。
使用 systemd 服務自動啟動 Wayland 合成器
如果您不想使用顯示管理器或 shell,
您可以嘗試通過上述 systemd 服務自動啟動 Wayland 合成器。將 labwc
替換為您想要使用的合成器。
/etc/systemd/system/labwc.service
[Unit] After=graphical.target systemd-user-sessions.service dev-dri-card0.device Wants=dev-dri-card0.device Conflicts=getty@tty1.service [Service] Type=simple User=yourusername WorkingDirectory=~ PAMName=login TTYPath=/dev/tty1 UnsetEnvironment=TERM StandardOutput=journal ExecStart=/bin/labwc [Install] WantedBy=graphical.target
其中 dev-dri-card0.device
由 udev 規則生成
/etc/udev/rules.d.99-dri.rules
ACTION=="add", SUBSYSTEM=="drm", KERNEL=="card0", TAG+="systemd"
故障排除
顏色校正
請參閱背光#色彩校正。
慢動作、圖形顯示故障和崩潰
Gnome-shell 用戶從 X 切換到 Wayland 時可能會遇到此問題。根本原因之一是可能用戶自己為基於 Xorg 的 gnome-shell 設置了 CLUTTER_PAINT=disable-clipped-redraws:disable-culling
變量。只需嘗試將變量從 /etc/environment
或其它 rc 文件中移除,即可查看是否一切恢復正常。
遠程顯示
- sway 使用的 wlroots包 從 0.10 版本開始通過 wayvnc包 提供了一個 VNC 後端。RDP 後端則已被移除。[10]
- 目前 mutter包 在編譯時就啟用了遠程桌面功能,詳情請參閱 [11] 和 gnome-remote-desktop包。
-
krfb包 為 kwin包 提供了一個 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-egl 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
另請參閱
- Wayland 在線文檔 (English)
- 官方倉庫 (English)
- Fedora:如何排查 Wayland 問題 (English)
- 我們現在是 Wayland 了! (English) - "Wayland 可用了嗎?"的更新版本
- Wayland 項目匯總 (English)
- 光標主題
- Arch Linux 論壇討論 (English) (頁面將持續關注 Wayland 信息 ,如有興趣請留意)
- i3 遷移指南 - i3 上常用 X11 應用的 Wayland 替代品 (English)
- Wayland Explorer - 閱讀 Wayland 文檔的更好方法 (English)
- 如何判斷應用程式是否在使用 XWayland (English)