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