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