niri 調試選項完全指南debug 配置塊與渲染調試快捷鍵詳解【免費下載鏈接】niriA scrollable-tiling Wayland compositor.項目地址: https://gitcode.com/GitHub_Trending/ni/niri導讀niri 是一個可滾動平鋪的 Wayland 合成器其配置文件中隱藏著一組專門用于故障排查與實驗的調試選項debug配置塊以及三條渲染可視化快捷鍵。本文基于 docs/wiki/Configuration:-Debug-Options.md 整理逐一講解全部 21 個調試選項與 3 個調試鍵綁定的用途、適用場景與配置寫法并結合 niri 源碼如 niri-config/src/debug.rs、src/backend/tty.rs、src/render_helpers/debug.rs說明其底層實現原理。讀完本文你將能夠在遇到直通掃描direct scanout、光標閃爍、DRM 設備沖突、窗口聚焦異常、VRR 抖動等疑難問題時快速定位并配置正確的調試開關。??重要警告這些調試選項不受 配置破壞性變更策略 的保護。它們屬于僅供調試或存在已知問題的實驗性功能不適用于日常使用隨時可能發生變更或失效升級 niri 時請保持謹慎。一、所有調試選項一覽niri 的調試配置統一放在debug {}配置塊中絕大多數是布爾開關Flag少數接受字符串參數如設備路徑或渲染預覽模式。以下是一個包含全部選項的參考配置可直接對照使用debug { preview-render screencast // preview-render screen-capture enable-overlay-planes disable-cursor-plane disable-direct-scanout restrict-primary-scanout-to-matching-format force-disable-connectors-on-resume render-drm-device /dev/dri/renderD129 ignore-drm-device /dev/dri/renderD128 ignore-drm-device /dev/dri/renderD130 force-pipewire-invalid-modifier dbus-interfaces-in-non-session-instances wait-for-frame-completion-before-queueing emulate-zero-presentation-time disable-resize-throttling disable-transactions keep-laptop-panel-on-when-lid-is-closed disable-monitor-names strict-new-window-focus-policy honor-xdg-activation-with-invalid-serial skip-cursor-only-updates-during-vrr deactivate-unfocused-windows disable-10bit-output }從源碼結構看niri-config/src/debug.rs 中的Debug結構體完整對應了上述每一個字段其中render-drm-device與ignore-drm-device使用PathBuf類型preview-render使用PreviewRender枚舉Screencast/ScreenCapture其余均為布爾標志。在 niri 配置的多文件合并機制MergeWith下這些選項也可以通過 配置 include 機制 分散寫入多個配置文件后合并生效。二、渲染與直通掃描Direct Scanout相關選項preview-render讓 niri 以與屏幕錄制screencast或屏幕捕獲screen capture完全相同的方式渲染顯示器畫面。也就是說它會把渲染目標從常規的RenderTarget::Output切換為Screencast或ScreenCapture從而在真實屏幕上預覽錄制/捕獲時客戶端的實際渲染效果。典型用途預覽block-out-from窗口規則Window Rule的實際遮擋效果——因為某些遮擋與裁剪只在錄制/捕獲模式下才會體現。debug { preview-render screencast // preview-render screen-capture }源碼佐證在 src/niri.rs 的渲染入口中當渲染目標為Output且配置了preview_render時會直接將其改寫為對應的錄制目標if ctx.target RenderTarget::Output { if let Some(preview) self.config.borrow().debug.preview_render { ctx.target match preview { PreviewRender::Screencast RenderTarget::Screencast, PreviewRender::ScreenCapture RenderTarget::ScreenCapture, }; } }enable-overlay-planes允許 niri 在**疊加平面overlay plane**上執行直通掃描。注意主平面primary plane上的直通掃描始終是開啟的此選項只額外放開疊加平面。debug { enable-overlay-planes }?? 在部分硬件上某些動畫期間開啟疊加平面直通掃描可能會導致掉幀這正是它默認關閉的原因。實現上該選項對應 src/backend/tty.rs 中的FrameFlags::ALLOW_OVERLAY_PLANE_SCANOUT標志而 DRM 合成器渲染時正是依據這些FrameFlags決定是否將窗口 buffer 直接提交到硬件平面。disable-cursor-plane禁用光標平面cursor plane此時光標會與畫面的其他部分一起合成渲染而不是由硬件光標平面直接呈現。debug { disable-cursor-plane }典型用途繞過特定硬件上的驅動 bug例如某些顯卡的光標平面出現撕裂、花屏或閃爍時。源碼中對應移除FrameFlags::ALLOW_CURSOR_PLANE_SCANOUT見 src/backend/tty.rs強制光標走普通渲染管線。disable-direct-scanout同時禁用主平面與疊加平面的直通掃描即所有窗口內容一律先經合成器渲染再輸出。debug { disable-direct-scanout }源碼中會同時移除主平面掃描標志與ALLOW_OVERLAY_PLANE_SCANOUT見 src/backend/tty.rs。此選項可與enable-overlay-planes形成對照實驗前者單獨測試疊加平面直通后者徹底關閉所有直通掃描。restrict-primary-scanout-to-matching-format將主平面直通掃描**限制為窗口 buffer 格式與合成 swapchain 格式完全一致**的情況。debug { restrict-primary-scanout-to-matching-format }背景與注意事項此標志可以避免在合成模式 ? 直通掃描模式切換時發生意料之外的帶寬變化項目計劃在將來實現告知客戶端合成 swapchain 格式的能力后將其設為默認開啟就目前而言它可能會阻止某些客戶端作者自述如 mpv在特定機器上直通掃描到主平面。skip-cursor-only-updates-during-vrr自 25.08 版本起可用。在**可變刷新率VRR**激活期間跳過由僅光標移動引發的屏幕重繪。debug { skip-cursor-only-updates-during-vrr }典型用途某些游戲不在內部繪制光標移動光標會引發 VRR 刷新率忽高忽低的抖動此選項可以規避這種不穩定的 VRR 波動。已知缺陷當前實現存在問題——如果沒有任何內容在驅動重繪例如靜止的游戲畫面由于光標移動不再觸發重繪畫面會看起來完全凍結。源碼實現在 src/backend/tty.rs 中開啟該選項后只要當前輸出的幀時鐘處于 VRR 狀態就會在幀標志中加入FrameFlags::SKIP_CURSOR_ONLY_UPDATES。三、顯示器、DRM 設備與輸出相關選項force-disable-connectors-on-resume自 26.04 版本起可用。在 niri 恢復運行時TTY 切換或從掛起中喚醒強制禁用所有輸出這會導致所有輸出執行一次 modeset/黑屏。debug { force-disable-connectors-on-resume }典型用途如果 TTY 切換后 niri 渲染出現花屏或顯示器無法點亮可以嘗試此標志強制讓輸出經歷一次完整的重新初始化。從源碼看該標志在會話恢復邏輯中被讀取見 src/backend/tty.rs用于決定恢復時是否強制禁用連接器。render-drm-device覆蓋 niri 用于所有渲染的 DRM 設備接受一個渲染節點render node路徑作為參數。debug { render-drm-device /dev/dri/renderD129 }典型用途當默認選中的主 GPU 不正確時可用它強制 niri 使用另一塊 GPU例如核顯/獨顯切換場景。其字段類型為OptionPathBuf見 niri-config/src/debug.rs。ignore-drm-device自 25.11 版本起可用。列出 niri應忽略的 DRM 設備可以重復指定多次。debug { ignore-drm-device /dev/dri/renderD128 ignore-drm-device /dev/dri/renderD130 }典型用途**GPU 直通GPU passthrough**場景下不希望 niri 打開某個設備時使用。源碼中對應ignored_drm_devices: VecPathBuf見 niri-config/src/debug.rs支持追加合并因此你可以在不同配置文件中分別忽略不同設備。disable-monitor-names自 0.1.10 版本起可用。禁用顯示器的 make/model/serial 名稱效果等同于 niri 無法從 EDID 中讀取到這些信息。debug { disable-monitor-names }典型用途規避 0.1.9 與 0.1.10 版本中同時連接兩臺 make/model/serial 完全相同的顯示器時存在的崩潰問題。遇到該崩潰時升級前可用此標志臨時繞過。disable-10bit-output自下一個發布版本起可用。默認情況下niri 會優先嘗試向顯示器輸出10-bit 顏色格式失敗后再回退到 8-bit。但在某些Intel NVIDIA 混合 GPU組合上這目前可能引發問題屏幕不亮、只顯示白色等。debug { disable-10bit-output }在 Smithay 修復該問題之前可以設置此標志禁用 10-bit 輸出。源碼佐證在 src/backend/tty.rs 創建 DRM 合成器時會根據該標志從SUPPORTED_COLOR_FORMATS_10BIT與SUPPORTED_COLOR_FORMATS兩套格式列表中選取實際可用的顏色格式let color_formats if self.config.borrow().debug.disable_10bit_output { SUPPORTED_COLOR_FORMATS[..] } else { SUPPORTED_COLOR_FORMATS_10BIT[..] }四、幀呈現、合成同步與性能診斷選項wait-for-frame-completion-before-queueing在每一幀完成渲染之后、交給 DRM 之前先等待其徹底完成。debug { wait-for-frame-completion-before-queueing }典型用途診斷某些同步synchronization與性能問題——例如懷疑多緩沖隊列掩蓋了渲染耗時或幀提交節奏異常時可以用它放慢并暴露真實的完成時機。emulate-zero-presentation-time模擬 DRM 返回零未知presentation time的情況。debug { emulate-zero-presentation-time }背景NVIDIA 專有驅動上確實存在返回零呈現時間的情況因此此標志用于測試 niri 在那些系統上不會壞得太嚴重。disable-resize-throttling自 0.1.9 版本起可用。禁用發送給窗口的 resize 事件節流throttling。默認行為快速縮放如交互式拖動縮放時窗口只有在為上一次請求的尺寸完成一次 commit 之后才會收到下一個新尺寸。這一機制是resize 事務transactions正常工作的前提同時也幫助某些不擅長批量處理合成器連續 resize 事件的客戶端。禁用后果niri 會盡可能快地向窗口發送 resize——可能快得驚人例如在 1000 Hz 鼠標上。debug { disable-resize-throttling }disable-transactions自 0.1.9 版本起可用。禁用事務機制resize 與 close 事務。默認行為必須同時縮放的窗口會一起縮放。例如同一列中的所有窗口必須同時調整尺寸才能保證列總高度等于屏幕高度、各窗口寬度一致。事務機制讓 niri等待所有窗口完成縮放之后再把它們放在同一幀里同步顯示。重要關聯為了讓事務正常工作不應禁用 resize 節流即不要與上一個disable-resize-throttling同時使用。debug { disable-transactions }五、屏幕錄制Screencasting與 D-Bus 相關選項force-pipewire-invalid-modifier自 25.01 版本起可用。強制 PipeWire 屏幕錄制使用invalid modifier即使 DRM 提供了更多 modifier 也如此。debug { force-pipewire-invalid-modifier }典型用途測試不支持 modifier 的驅動才會命中的 invalid modifier 代碼路徑。這有助于在開發/調試時模擬老式或受限驅動的行為。dbus-interfaces-in-non-session-instances即使 niri不是以--session方式運行也讓它創建 D-Bus 接口。debug { dbus-interfaces-in-non-session-instances }典型用途測試屏幕錄制相關的改動時無需重新登錄即可啟動一個測試實例來驗證。??注意當你關閉測試實例后主 niri 實例目前不會自動收回這些接口因此最終仍需重新登錄一次屏幕錄制功能才會恢復正常。六、窗口聚焦與 xdg-activation 相關選項strict-new-window-focus-policy自 25.01 版本起可用。禁用新窗口自動聚焦的啟發式規則。啟用后只有攜帶有效 xdg-activation token 且主動激活自身的窗口才會獲得焦點。debug { strict-new-window-focus-policy }源碼佐證該標志在 src/handlers/compositor.rs 的新窗口/激活處理邏輯中被讀取用于決定是否跳過默認的啟發式聚焦。honor-xdg-activation-with-invalid-serial自 25.05 版本起可用。背景Discord、Telegram 等被廣泛使用的客戶端在用戶點擊其托盤圖標或通知時會生成全新的 xdg-activation token。大多數情況下這些新 token 的serial 是無效的——因為應用必須處于聚焦狀態才能拿到有效 serial而用戶點擊托盤/通知通常恰恰是因為應用并未聚焦、希望讓它聚焦。默認行為niri 會忽略 serial 無效的 xdg-activation token以防止窗口隨意搶占焦點。這會導致上述應用點擊托盤圖標或通知后無法獲得焦點。此調試標志讓 niri接受這類無效 serial 的 token使上述應用在點擊托盤圖標或通知后能夠獲得焦點。debug { honor-xdg-activation-with-invalid-serial }配套使用可以配合 on-xdg-activate 窗口規則針對單個窗口精確控制 niri 在接受到 xdg-activation 請求時的行為。有意思的細節點擊通知時通知守護進程會向應用發送一個完全有效的激活 token但這些應用Electron、Qt 等似乎直接忽略了它。未來若這些應用/工具包修復了該問題此調試標志或許就不再需要了。源碼佐證該標志在 src/handlers/mod.rs 的 xdg-activation 請求處理中被讀取決定是否放行無效 serial 的激活請求。deactivate-unfocused-windows自 25.08 版本起可用。背景某些客戶端特別是Chromium 與 Electron 系如 Teams、Slack會錯誤地使用 xdg 窗口狀態中的Activated而非鍵盤焦點來判斷是否為新消息發送通知在哪里顯示 IME 彈出窗口等。而 niri 出于減少不必要動畫的考慮會在未聚焦的工作區和不可見的標簽頁窗口上保留Activated狀態從而暴露這些應用中的 bug。此調試標志設置后niri 會丟棄所有未聚焦窗口的Activated狀態從而繞開上述問題。debug { deactivate-unfocused-windows }源碼佐證該選項通過 src/layout/mod.rs 的布局選項傳入并在浮動窗口與滾動布局的聚焦更新邏輯中生效見 src/layout/floating.rs 與 src/layout/scrolling.rs。七、其他選項keep-laptop-panel-on-when-lid-is-closed自 0.1.10 版本起可用。默認行為合上筆記本蓋子時niri 會關閉內置顯示器。此調試標志關閉這一行為合蓋后保持內置顯示器開啟。debug { keep-laptop-panel-on-when-lid-is-closed }八、調試鍵綁定Key Bindings以下并非調試選項而是鍵綁定用于在運行時可視化渲染與合成狀態對排查問題極其直觀。它們定義在binds {}配置塊中binds { ModShiftCtrlT { toggle-debug-tint; } ModShiftCtrlO { debug-toggle-opaque-regions; } ModShiftCtrlD { debug-toggle-damage; } }這三個動作在 niri-config/src/binds.rs 中均有對應的Action枚舉變體ToggleDebugTint、DebugToggleOpaqueRegions、DebugToggleDamage并由 src/input/mod.rs 的鍵位分發邏輯執行——包括切換狀態、立即請求全量重繪queue_redraw_all等。這也意味著它們可以像任何普通綁定一樣自由更換組合鍵甚至通過 IPC 觸發。toggle-debug-tint將所有 surface 著色為綠色正在被直通掃描direct scanout的除外。典型用途快速驗證直通掃描是否真正生效——被直通掃描的畫面不會被染綠。binds { ModShiftCtrlT { toggle-debug-tint; } }源碼佐證debug_tint標志保存在后端狀態中見 src/backend/tty.rs渲染時若開啟則通過DebugFlags::TINT通知渲染器進行綠色著色見 src/backend/tty.rs切換后還會通過queue_redraw_all()強制全量重繪。debug-toggle-opaque-regions自 0.1.6 版本起可用。將標記為不透明opaque的區域著色為藍色其余渲染元素著色為紅色。典型用途檢查 Wayland surface 與內部渲染元素如何標記自身的不透明區域——這是渲染性能優化的重要手段不透明區域可以跳過混色與底層繪制。binds { ModShiftCtrlO { debug-toggle-opaque-regions; } }源碼佐證實現在 src/render_helpers/debug.rs 的push_opaque_regions中對每個渲染元素的不透明區域填充半透明藍色Color32F::from([0., 0., 0.2, 0.2])對其余半透明區域填充半透明紅色Color32F::from([0.3, 0., 0., 0.3])。該功能通過 src/niri.rs 的渲染包裝層注入。debug-toggle-damage將受損區域damaged regions著色為紅色。典型用途直觀觀察每一幀的 damage 區域分布驗證 niri 的局部重繪damage tracking是否按預期工作——例如滾動窗口時只重繪必要區域而非整屏刷新。binds { ModShiftCtrlD { debug-toggle-damage; } }源碼佐證實現在 src/render_helpers/debug.rs 的draw_damage中它調用 damage tracker 的damage_output取出當前幀的損壞矩形并以紅色Color32F::from([0.3, 0., 0., 0.3])填充后插入到渲染元素列表最底層。DRM 與 Winit 后端均在渲染時調用它見 src/backend/tty.rs 與 src/backend/winit.rs。九、總結如何系統性地使用調試選項先從癥狀定位方向顯示器不亮/花屏 →force-disable-connectors-on-resume、disable-10bit-output光標閃爍 →disable-cursor-plane畫面撕裂/性能異常 →disable-direct-scanout、enable-overlay-planes、wait-for-frame-completion-before-queueing焦點被搶 →strict-new-window-focus-policy、honor-xdg-activation-with-invalid-serial、deactivate-unfocused-windows。善用渲染可視化toggle-debug-tint驗證直通掃描debug-toggle-opaque-regions檢查不透明區域標記debug-toggle-damage觀察損壞區域——三者組合可以快速定位絕大多數渲染問題。務必逐項隔離測試調試選項之間存在相互影響如disable-resize-throttling與disable-transactions的聯動建議一次只啟用一個確認效果后再疊加。牢記風險所有調試選項不受破壞性變更策略保護可能在任何版本中變更或移除在向 Nvidia.md、IPC.md 等場景排查問題時優先參考當前版本文檔與 Getting-Started.md 的配置加載方式確保配置位于正確的配置文件層級。【免費下載鏈接】niriA scrollable-tiling Wayland compositor.項目地址: https://gitcode.com/GitHub_Trending/ni/niri創作聲明：本文部分內容由AI輔助生成（AIGC），僅供參考