niri guide usage

Niri 使用指南

Niri 是可滚动平铺的 Wayland 合成器。窗口沿水平方向组成无限条带，每一列可以放一个或多个窗口；新窗口不会强制缩小已有窗口，而是扩展到右侧，通过水平移动浏览

本文记录当前 dotfiles 的真实使用方式。Mod 表示 Super，也就是 Windows 键

5 分钟上手

快捷键	功能
Mod-t	打开 Kitty
Mod-d	打开 Noctalia 应用启动器
Mod-e	打开 Dolphin
Mod-Tab	打开或关闭 Niri Overview
Alt-Tab / Alt-Shift-Tab	切换当前工作区的最近窗口
Mod-q	关闭窗口
Mod-Alt-l	锁屏
Alt-v	打开剪贴板历史

登录时配置会自动启动 Ghostty 和 Firefox；Mod-t 启动的是 Kitty，两者不是同一个默认终端概念

焦点与窗口移动

快捷键	功能
Mod-h/j/k/l	向左、下、上、右移动焦点
Mod-Ctrl-h/j/k/l	向对应方向移动列或窗口
Mod-Home / Mod-End	聚焦第一列或最后一列
Mod-Ctrl-Home / Mod-Ctrl-End	把当前列移动到最前或最后

Niri 的水平单位是“列”，垂直单位是列中的“窗口”。因此 h/l 操作列，j/k 操作同列窗口或相邻工作区

列、窗口大小与布局

快捷键	功能
Mod-Left/Right	列宽减少或增加 10%
Mod-Up/Down	窗高增加或减少 10%
Mod-r / Mod-Shift-r	正向或反向切换列宽预设
Mod-Ctrl-Shift-r	切换窗口高度预设
Mod-Ctrl-r	重置窗口高度
Mod-f	最大化当前列
Mod-Shift-f	当前窗口全屏
Mod-m	窗口扩展到屏幕边缘
Mod-Ctrl-f	当前列扩展到可用宽度
Mod-c	居中当前列
Mod-Ctrl-c	居中所有可见列
Mod-v	切换窗口浮动状态
Mod-Shift-v	在浮动层和平铺层之间切换焦点

当前默认列宽为屏幕的 1/2，预设为 1/3、1/2、2/3。窗口间距为 0，使用 2px 边框、圆角和阴影

把窗口吸入或移出列

快捷键	功能
Mod-[	向左侧列吸入或移出窗口，处于最左列时自动反向
Mod-]	向右侧操作；多窗口列时优先把窗口移出

这两个快捷键调用本地脚本并依赖 niri msg -j 与 jq。脚本当前写死 /home/dev/.config/niri，复制配置到其他用户名时需要修改路径

工作区

快捷键	功能
Mod-u/i	切换到下一个或上一个工作区
Mod-Ctrl-u/i	把当前列移动到下一个或上一个工作区
Mod-Shift-u/i	向下或向上重排当前工作区
Mod-滚轮上下	切换工作区
Mod-Ctrl-滚轮上下	把当前列移动到相邻工作区
Mod-Shift-滚轮上下	水平切换列

Page Up/Page Down 也提供对应操作

多显示器

快捷键	功能
Mod-Shift-h/j/k/l	聚焦对应方向的显示器
Mod-Ctrl-Shift-h/j/k/l	把当前列移动到对应显示器

单显示器无需写 output 配置。查看真实输出名称和参数：

niri msg outputs

~/.config/niri/output.kdl 当前只有被禁用的示例，不能将其中的分辨率视为实际配置

截图

快捷键	功能
F1	打开 mark-shot 截图与标注
Ctrl-Print	截取整个屏幕
Alt-Print	截取当前窗口

Niri 内置截图保存到 ~/Pictures/Screenshots/

mark-shot 的标注界面中可按 F3 贴图；OCR 需要额外安装 rapidocr 和 onnxruntime

音量、亮度与媒体

键盘的音量、麦克风、播放、上一首、下一首和亮度键均已配置，并允许在锁屏状态下使用。音量与亮度由 Noctalia 显示 OSD

状态栏与桌面面板

• Noctalia 提供状态栏、托盘、Wi-Fi、日期、通知历史和会话菜单
• Mod-d 打开 Noctalia 应用启动器
• Alt-v 打开 Noctalia 剪贴板历史
• 底部 Dock 默认隐藏，鼠标触碰屏幕底边时显示
• Mod-Tab 进入 Niri Overview，Noctalia backdrop 只在 Overview 中显示

壁纸与动态配色

Noctalia 从 ~/Pictures 管理壁纸，并每 600 秒按配置轮换。主题使用壁纸 m3-content 取色，Noctalia UI 和 Niri 窗口边框会随壁纸更新

Niri 配色由 Noctalia 内置 niri 模板生成到 ~/.config/niri/noctalia.kdl，该文件是运行时产物，不应手工维护。Kitty 和 Tmux 保持静态 Catppuccin，不跟随壁纸取色

自动锁屏与息屏

• 自动登录进入 Niri 后立即请求 Noctalia 锁屏
• 空闲 900 秒由 Noctalia 锁屏
• 空闲 1020 秒关闭显示器，输入后重新点亮
• 休眠前等待 Noctalia 真正取得 session lock
• 没有配置空闲自动休眠，便于 Sunshine 持续提供远程连接
• 显示器熄灭时 Sunshine 仍可接受 Moonlight 连接

合盖行为由 systemd-logind 单独控制，不等同于空闲策略

桌面组件地图

Niri 只是合成器，不是完整桌面环境：

组件	职责
Noctalia	状态栏、托盘、启动器、通知与历史、OSD、剪贴板、壁纸、锁屏、空闲策略和 Polkit 认证 UI
wl-clipboard	命令行复制、粘贴与测试工具
xwayland-satellite	X11 应用兼容
XEmbed SNI Proxy	兼容仍使用旧 XEmbed 协议的托盘应用

Waybar、Mako、Fuzzel、Awww、Matugen、Hyprlock、Swayidle、Cliphist、Quickshell 剪贴板和 SwayOSD 的配置仍可作为回退参考，但不再是当前默认桌面链路

配置与排错

配置入口为 ~/.config/niri/config.kdl，并拆分加载：

layout.kdl
blur.kdl
rules.kdl
animations.kdl
binds.kdl
output.kdl      # 可选
noctalia.kdl    # 可选、由 Noctalia niri 模板生成
nvidia.kdl      # 可选、由检测脚本生成

Noctalia 的模块化配置位于 ~/.config/noctalia/。界面语言在 shell.toml 中单独设置：

[shell]
lang = "zh-Hans"

该字段控制 Noctalia UI 语言，与系统 locale、日期格式和时区设置相互 独立；保存后 Noctalia 会热重载

保存配置后 Niri 会热重载。修改前后可检查语法：

niri validate

常用 IPC：

niri msg windows
niri msg workspaces
niri msg outputs
niri msg action focus-column-left

常见问题：

• 中文显示方块：用 fc-match -s 'sans-serif:lang=zh' 检查 CJK fallback，再运行 fc-cache -fv
• 应用集体退出或无法启动但 Niri 仍存活：优先检查 systemd user session 与 D-Bus
• 输入法候选窗被平铺：确认 fcitx window rule 仍匹配
• 修改显示器参数无效：确认 output.kdl 中目标节点没有被 /- 禁用
• consume 快捷键失效：检查脚本路径和 jq
• Noctalia 面板无响应：检查 systemctl --user status noctalia.service 和 journalctl --user -u noctalia.service
• 壁纸一直模糊：确认 noctalia-backdrop 的 Niri layer rule 使用 place-within-backdrop true

完整 Arch 安装、Niri 生态原理、字体和故障记录保存在：

~/Documents/note/StudyNote/Linux/Arch/
~/Documents/note/StudyNote/Linux/Arch/Niri/