Niri 项目中的 NumLock 状态同步问题分析与解决方案

NumLock 键状态同步问题是一个在 Wayland 复合器中常见的输入处理挑战。在 Niri 项目中，开发者发现了一个有趣的 NumLock 行为异常：系统启动后 NumLock LED 指示灯正常亮起，但数字小键盘功能却需要等待约一分钟或按下任意修饰键后才能激活。

问题现象

用户报告显示，在 Niri 25.02 版本中，当配置文件中启用 numlock 选项后，系统会出现以下异常行为：

1. 系统启动后，NumLock LED 指示灯立即亮起
2. 数字小键盘功能却未实际激活，仍保持方向键/功能键模式
3. 需要等待约一分钟或按下任意修饰键（如 Ctrl、Alt 等）后，数字小键盘功能才会正常激活

这一问题不仅出现在内置键盘上，外接键盘也表现出相同行为。有趣的是，该问题在多个 Linux 发行版（Arch 和 Debian）上都能复现，且不受启动方式（通过 greetd 或直接 tty 启动）影响。

技术分析

经过开发者深入调查，发现问题根源在于键盘状态同步机制。在 Wayland 架构下，输入设备管理由复合器负责，而 NumLock 状态需要正确同步到所有连接的键盘设备。

关键发现包括：

1. 状态指示与实际功能不同步：LED 指示灯能立即响应，但键位映射需要额外触发
2. 修饰键按下会强制刷新键盘状态
3. 问题与键盘连接时序无关，因为即使键盘在启动时就已连接，问题依然存在

解决方案

问题最终被定位到 Smithay 库（Niri 使用的 Wayland 库）中的键盘状态处理逻辑。修复方案主要涉及以下修改：

1. 在设置修饰键状态后，正确更新内部状态缓存
2. 确保状态变更能正确传播到所有键盘设备
3. 修复状态序列化逻辑，防止状态丢失

核心修复是在设置修饰键状态时，同时更新内部状态缓存和序列化数据，确保状态变更能正确持久化。

验证与影响

修复后的版本（8347cc2）在多台设备和不同键盘上测试通过：

1. 内置键盘和外接键盘均能立即正确响应
2. NumLock 状态在系统启动时即正确应用
3. 键盘热插拔场景下状态同步正常

这一修复不仅解决了 NumLock 问题，也为其他键盘状态同步场景提供了更可靠的基础。对于终端用户而言，这意味着更一致、更可靠的输入体验，特别是在依赖数字小键盘的工作场景中。

技术启示

该案例展示了 Wayland 输入处理中的几个重要方面：

1. 状态同步的重要性：视觉反馈（LED）与实际功能必须一致
2. 修饰键处理的特殊性：它们常常作为状态变更的触发器
3. 库级修复的影响：底层库的微小调整可能解决上层应用的显著问题

对于 Wayland 复合器开发者，这一案例强调了全面测试输入设备各种状态和连接场景的重要性，特别是在涉及状态同步的场景中。