rvaiya--keyd/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

Impetus

Linux 缺少一套好用的按键重映射方案。要想获得满意的效果，往往需要组合使用多种工具（例如 xcape、xmodmap），而最终效果还常常绑定在特定环境（如 X11）上。keyd 试图通过提供一个灵活的全系统守护进程来解决这一问题；它利用内核级输入原语（evdev、uinput）来重映射按键。

关于 v2 的说明

自首次发布以来，配置格式已经历多次迭代。若要从 v1 迁移配置，最好重新阅读 man page (man keyd)。

另请参阅：changelog。

目标

• 速度 （用 C 编写、手工调优的输入循环，耗时 <<1ms）
• 简洁 （直观易懂的配置格式）
• 一致性 （修饰键默认就能与层（layer）配合良好）
• 模块化 （遵循 UNIX 哲学的核心，可通过 IPC 机制扩展）

特性

keyd 拥有多项独特功能，其中许多传统上只出现在自定义键盘固件（如 QMK）中，也有一些是 keyd 独有的。

其中较有意思的有：

• 层（layer）（支持混合修饰键（hybrid modifiers）).）
• 按键过载（tap/hold 行为不同）。
• 针对特定键盘的配置。
• 即时重映射（无需再刷固件 :))。
• 客户端-服务器模型，便于脚本化以及与显示服务器无关的应用重映射。（当前内置对 X、sway 和 gnome（Wayland）的支持。）
• 全系统配置（在 VT 中也可用）。
• 对修饰键过载的一等支持。
• Unicode 支持。

keyd 适合这些人：

• 想尝试自定义层（layer）（即自定义 Shift 键） 和 oneshot 修饰键。
• 想在同一台机器上使用多台键盘、各自采用不同布局。
• 希望能够重映射 C-1，同时不破坏修饰键语义。
• 想要一种易于理解的键盘配置格式。
• 喜欢遵循 Unix 哲学的小型守护进程。
• 想把 Control 和 Escape 键放到它们本该在的位置。
• 希望切换到 VT 调试问题时，不会弄乱自己的键位映射。

keyd 不是：

• 用于编程单个按键按下/抬起事件的工具。

依赖

• 你喜爱的 C 编译器
• Linux 内核头文件（大多数系统上已自带）

可选

• python （用于应用特定重映射）
• python-xlib （仅用于 X 支持）
• dbus-python （仅用于 KDE 支持）

安装

注意： master 作为开发分支，版本发布之间偶尔会有问题。发布版本已打标签,，可视为稳定版。

从源码安装

git clone https://github.com/rvaiya/keyd
cd keyd
make && sudo make install
sudo systemctl enable --now keyd

快速入门

1. 安装并启动 keyd（例如 sudo systemctl enable keyd --now）

2. 将以下内容放入 /etc/keyd/default.conf：

[ids]

*

[main]

# Maps capslock to escape when pressed and control when held.
capslock = overload(control, esc)

# Remaps the escape key to capslock
esc = capslock

可通过 keyd monitor 命令获取键名。请注意，在 keyd 运行期间，该命令的输出会对应 keyd 的输出。若要查看原始输入事件，需先停止 keyd，再运行该命令。更多细节请参阅 man page。

3. 运行 sudo keyd reload 以重新加载配置。

4. 更完整的说明请参阅 man page（man keyd）。

配置错误会出现在日志输出中，也可通过系统的服务管理器以常规方式查看（例如 sudo journalctl -eu keyd）。

注意：错误的配置文件可能使你的机器无法使用。 若遇到这种情况，特殊按键序列 backspace+escape+enter 应能让 keyd 终止运行。

部分鼠标（例如 Logitech MX Master）能够发出按键事件， 因此会被通配符 id 匹配。可能需要显式将它们加入黑名单。

应用特定重映射（实验性）

• 将自己加入 keyd 组：

  usermod -aG keyd <user>

• 填写 ~/.config/keyd/app.conf：

例如

[alacritty]

alt.] = macro(C-g n)
alt.[ = macro(C-g p)

[chromium]

alt.[ = C-S-tab
alt.] = macro(C-tab)

• 运行：

  keyd-application-mapper

你可能希望将 keyd-application-mapper -d 放在 显示服务器初始化逻辑中的某处（例如 ~/.xinitrc），除非你运行的是 Gnome。

更多细节请参阅 man page。

SBC 支持

在 Giorgi Chavchanidze 的贡献下，已通过 usb-gadget 为单板计算机（SBC）加入实验性支持。

详情请参阅 usb-gadget.md。

软件包

部分发行版已有第三方软件包。若希望将你的发行版加入列表，请提交 PR。这些软件包由社区成员好心维护，作者不对其承担个人责任。

Alpine Linux

keyd 软件包由 @jirutka. 维护。

Arch

Arch Linux 软件包由 Arch 打包者维护。

Debian

Debian 13（"trixie"）及更高版本提供 keyd 软件包。安装方法：

sudo apt install keyd

Fedora

COPR 软件包由 @alternateved. 维护。

Gentoo

GURU 软件包由 jack@pngu.org 维护。

openSUSE

opensuse 软件包由 @bubbleguuum. 维护。

可使用 sudo zypper in keyd 轻松安装。

Ubuntu

Ubuntu 25.04（"plucky"）及更高版本提供 keyd 软件包。安装方法：

sudo apt install keyd

此外，可将最新 Debian 软件包反向移植到各 Ubuntu 版本，见 ppa:keyd-team/ppa archive.

Void Linux

xbps 软件包由 @Barbaross. 维护。

可使用 sudo xbps-install -Su keyd 轻松安装。

示例 1

[ids]

*

[main]

leftshift = oneshot(shift)
capslock = overload(symbols, esc)

[symbols]

d = ~
f = /
...

示例 2

这会覆盖 macOS 用户可能更熟悉的一些特定 Alt 组合键， 同时保持其余映射不变。

[ids]
*

[alt]

x = C-x
c = C-c
v = C-v

a = C-a
f = C-f
r = C-r
z = C-z

推荐配置

许多用户可能并不想充分利用 keyd 的全部能力。 若你只想获得一些简单的生活质量改进，我推荐以下配置：

[ids]

*

[main]

shift = oneshot(shift)
meta = oneshot(meta)
control = oneshot(control)

leftalt = oneshot(alt)
rightalt = oneshot(altgr)

capslock = overload(control, esc)
insert = S-insert

该配置将 capslock 过载为：轻按作 escape，按住作 control； 并将所有修饰键重映射为 "oneshot" 键。因此，要输入字母 A， 你现在可以轻按 shift 再按 a，而不必一直按住 shift。 最后，它将 insert 重映射为 S-insert（在 X11 上用于粘贴）。

常见问题

启用 keyd 后，触控板为何会干扰输入？

libinput 是大多数 Wayland 和 X11 环境使用的高级输入组件，其中包含一项称为「打字时禁用」（disable-while-typing）的功能，可在打字时禁用触控板。

为实现这一点，它需要区分内置键盘与外接键盘，其做法是为特定硬件硬编码规则（称为 quirks）。由于 keyd 会创建一个虚拟设备，该设备同时涵盖外接键盘与集成键盘，因此你需要让 libinput 将 keyd 虚拟设备视为内置设备。

可通过在 /etc/libinput/local-overrides.quirks（若不存在可能需要新建）中添加以下内容来实现：

[Serial Keyboards]

MatchUdevType=keyboard
MatchName=keyd*keyboard
AttrKeyboardIntegration=internal

感谢 @mark-herbert42 和 @canadaduane 提供的原始解决方案。

xmodmap/setxkbmap/* 呢？

xmodmap 及其同类工具是显示服务器（display server）层面的工具，功能有限。keyd 是系统级方案，可实现分层（layering）和 oneshot 修饰键等高级功能。虽然部分 X 工具提供类似功能，但据我所知，没有哪款能像 keyd 这样灵活。

kmonad? 呢？

keyd 编写于数年前，目的是让我能在我不断扩充的键盘收藏上轻松试验不同布局。当时 kmonad 尚不存在，而像 QMK（启发 keyd 的自定义键盘固件）这类方案，是获得可比功能的唯一途径。发布 keyd 之后我才了解到 kmonad。kmonad 是一个目标相近的优秀项目，但采用了不同思路，设计哲学也不同。

值得注意的是，keyd 完全用 C 编写，兼顾性能与简洁，很可能永远不会像 kmonad（可用 Haskell 扩展）那样可配置。话虽如此，在作者看来，它在不到 2000 行 C 代码内提供了最有价值的功能，并附带一种与语言无关的简单配置格式。

为什么 keyd 不实现功能 X？

如果你觉得缺少某些功能或发现了 bug，欢迎在 GitHub 上提交 issue。keyd 秉持极简（但合理）的设计哲学，有意省略某些功能（例如以 root 身份执行任意可执行文件）。像 QMK 这类自定义键盘固件中已有的功能，是较好的纳入候选。

贡献

请参阅 CONTRIBUTING。 IRC 频道：oftc 上的 #keyd