keyd：Linux 下革命性的系统级键盘重映射守护进程

背景

在 Linux 生态系统中，长期以来缺乏一个优秀且统一的键盘重映射（key remapping）解决方案。虽然用户可以使用 xcape、xmodmap 等工具组合来实现特定需求，但这些工具往往存在明显的局限性：它们通常依赖于特定的显示服务器环境（如 X11），导致配置难以在不同桌面环境或虚拟终端（VT）间保持一致。这种碎片化的现状使得用户难以获得流畅、系统级的键盘体验。

keyd 的出现旨在解决这一痛点。作为一个灵活的系统级守护进程（daemon），keyd 利用内核级的输入原语（evdev 和 uinput）直接在驱动层进行键盘映射。这意味着它不依赖于特定的图形界面或显示服务器，能够提供更底层、更一致且高性能的键盘控制能力。

核心内容

keyd 的设计哲学深受 UNIX 哲学影响，强调速度、简单性、一致性和模块化。其核心配置格式经过多次迭代，旨在提供直观且强大的功能。以下是 keyd 的核心功能与技术特性详解：

1. 核心架构与性能

• 内核级操作：keyd 基于 evdev 和 uinput 工作，这意味着它可以在系统启动早期（包括虚拟终端 VT）生效，不受显示服务器（X11/Wayland）状态的影响。
• 极致性能：其输入循环由手写 C 语言代码实现，耗时极低（<<1ms），确保键盘响应无延迟。
• 模块化设计：核心通过 IPC（进程间通信）机制扩展，允许脚本化和模块化配置。

2. 高级键盘功能

keyd 引入了许多传统上仅在自定义键盘固件（如 QMK）中才能找到的功能，以及其独有的特性：

• 图层（Layers）：支持混合修饰键（hybrid modifiers），允许用户定义多层键盘布局。
• 按键重载（Key Overloading）：支持“轻按/长按”不同行为。例如，轻按 CapsLock 为 Esc，长按为 Ctrl。
• 一次性修饰键（Oneshot Modifiers）：按下修饰键后松开，下一次按键自动应用该修饰，无需持续按住。
• 即时重映射：配置更改即时生效，无需重启服务或闪烁屏幕。
• 客户端-服务器模型：支持脚本化操作，并具备显示服务器无关的应用程序重映射能力。目前原生支持 X、Sway 和 GNOME (Wayland)。
• Unicode 支持：允许输入特殊字符。

3. 配置与安装

• 配置格式：keyd 使用一种简单易懂的配置文件格式。
• 安装方式：
  • 源码编译：git clone 仓库后执行 make && sudo make install。
  • 启用服务：sudo systemctl enable --now keyd。
  • 包管理器：Arch Linux、Debian 13+、Ubuntu 25.04+、openSUSE、Void Linux 等主流发行版均已提供官方或社区维护的包。
• 安全机制：
  • 错误配置可能导致系统不可用。为此，keyd 提供了一个紧急恢复序列：同时按下 Backspace + Escape + Enter 可强制终止 keyd 进程，从而恢复键盘正常功能。
  • 日志可通过 journalctl -eu keyd 查看，以排查配置错误。

4. 应用程序特定重映射

keyd 支持基于应用程序的重映射，通过 ~/.config/keyd/app.conf 配置文件实现。例如：

• 在 Alacritty 中，将 Alt+] 映射为 Ctrl+g n（下一个标签页），Alt+[ 映射为 Ctrl+g p（上一个标签页）。
• 在 Chromium 中，将 Alt+[ 映射为 Ctrl+Shift+Tab。
• 这需要运行 keyd-application-mapper 守护进程，并通常需要在显示服务器初始化逻辑中添加该命令。

5. 与其他工具的对比

• vs xmodmap：xmodmap 是显示服务器级别的工具，功能有限且依赖 X11。keyd 是系统级解决方案，支持图层、一次性修饰键等高级功能，且兼容 Wayland。
• vs kmonad：kmonad 是一个类似目标的项目，但基于 Haskell，更注重可配置性和扩展性。keyd 则完全使用 C 语言编写，追求极致的性能和简洁性（代码量少于 2000 行），并提供语言无关的简单配置格式。

6. 常见问题与技巧

• 鼠标误匹配：某些鼠标（如 Logitech MX Master）会发送键盘信号，可能被 keyd 的通配符 ID 匹配。此时需要在配置中显式黑名单这些设备。
• libinput 冲突：Wayland/X11 中的 libinput 具有“打字时禁用触控板”功能，它通过硬编码规则识别内部键盘。由于 keyd 创建了一个虚拟键盘设备，需要手动在 /etc/libinput/local-overrides.quirks 中将该虚拟设备标记为内部键盘，以恢复此功能。
• 用户权限：需要将用户添加到 keyd 组（usermod -aG keyd <user>）以允许非 root 用户进行应用程序重映射。

关键要点

• 系统级覆盖：keyd 在内核输入层工作，解决了 X11/Wayland 分离导致的配置不一致问题，支持虚拟终端和图形界面无缝切换。
• QMK 级功能：提供了图层、按键重载（Tap/Hold）、一次性修饰键等高级功能，无需更换硬件键盘。
• 高性能与简洁：纯 C 语言编写，代码精简，响应延迟极低，配置格式直观。
• 应用感知重映射：支持针对不同应用程序（如浏览器、终端模拟器）应用不同的键盘布局。
• 安全恢复机制：内置 Backspace+Escape+Enter 紧急终止序列，防止配置错误导致系统锁死。
• 广泛的发行版支持：主流 Linux 发行版（Arch, Debian, Ubuntu, openSUSE, Void）均提供包支持。
• 与 libinput 集成：需手动配置 libinput 以识别 keyd 的虚拟键盘，确保“打字时禁用触控板”等功能正常工作。
• 设计哲学：作者倾向于 UNIX 哲学，追求小且专注的守护进程，而非庞大复杂的软件套件。

意义与影响

keyd 的出现填补了 Linux 键盘定制领域的一个重大空白。对于重度键盘用户、机械键盘爱好者以及追求高效工作流的开发者而言，keyd 提供了一种无需修改固件、无需依赖特定桌面环境即可实现高度个性化键盘布局的方案。

它打破了传统键盘重映射工具对图形界面的依赖，使得键盘配置成为系统基础设施的一部分，而非桌面环境的附属品。这不仅提升了用户体验的一致性，也为 Linux 输入子系统提供了更灵活的上层扩展能力。通过提供类似 QMK 的功能但保持软件层面的易用性和跨平台性，keyd 降低了高级键盘定制的门槛，推动了 Linux 桌面个性化定制的发展。同时，其简洁的设计和清晰的文档也为其他系统级工具的开发提供了良好的参考范例。