<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
> [English](./README.en.md) · [原始项目](https://github.com/rvaiya/keyd) · [上游 README](https://github.com/rvaiya/keyd/blob/HEAD/README.md)  
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

[![Kofi](https://badgen.net/badge/icon/kofi?icon=kofi&label)](https://ko-fi.com/rvaiya)

# Impetus

[![Packaging status](https://repology.org/badge/tiny-repos/keyd.svg)](https://repology.org/project/keyd/versions)

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

# 关于 v2 的说明

自首次发布以来，配置格式已经历多次迭代。若要从 v1 迁移配置，最好重新阅读 [man page](https://raw.githubusercontent.com/rvaiya/keyd/refs/heads/master/docs/keyd.scdoc) (`man keyd`)。

另请参阅：[changelog](docs/CHANGELOG.md)。

# 目标

  - 速度       （用 C 编写、手工调优的输入循环，耗时 <<1ms）
  - 简洁       （直观易懂的[配置格式](#sample-config)）
  - 一致性     （修饰键默认就能与[层（layer）配合良好](https://github.com/rvaiya/keyd/blob/6dc2d5c4ea76802fd192b143bdd53b1787fd6deb/docs/keyd.scdoc#L128)）
  - 模块化     （遵循 UNIX 哲学的核心，可通过 [IPC](https://github.com/rvaiya/keyd/blob/90973686723522c2e44d8e90bb3508a6da625a20/docs/keyd.scdoc#L391) 机制扩展）

# 特性

keyd 拥有多项独特功能，其中许多传统上只出现在自定义键盘固件（如 [QMK](https://github.com/qmk/qmk_firmware)）中，也有一些是 keyd 独有的。

其中较有意思的有：

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

### keyd 适合这些人：

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

### keyd 不是：

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

# 依赖

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

## 可选

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

# 安装

*注意：* master 作为开发分支，版本发布之间偶尔会有问题。发布版本已[打标签](https://github.com/rvaiya/keyd/tags),，可视为稳定版。

## 从源码安装

    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](src/vkbd/usb-gadget.md)。

## 软件包

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

### Alpine Linux

[keyd](https://pkgs.alpinelinux.org/packages?name=keyd) 软件包由 [@jirutka](https://github.com/jirutka). 维护。

### Arch

[Arch Linux](https://archlinux.org/packages/extra/x86_64/keyd/) 软件包由 Arch 打包者维护。

### Debian

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

```shell
sudo apt install keyd
```

### Fedora

[COPR](https://copr.fedorainfracloud.org/coprs/alternateved/keyd/) 软件包由 [@alternateved](https://github.com/alternateved). 维护。

### Gentoo

[GURU](https://gitweb.gentoo.org/repo/proj/guru.git/tree/app-misc/keyd) 软件包由 [jack@pngu.org](mailto:jack@pngu.org) 维护。

### openSUSE
[opensuse](https://software.opensuse.org//download.html?project=hardware&package=keyd) 软件包由 [@bubbleguuum](https://github.com/bubbleguuum). 维护。

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

### Ubuntu

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

```shell
sudo apt install keyd
```

此外，可将最新 Debian 软件包反向移植到各 Ubuntu 版本，见
[`ppa:keyd-team/ppa`
archive](https://launchpad.net/~keyd-team/+archive/ubuntu/ppa).

### Void Linux

[xbps](https://github.com/void-linux/void-packages/tree/master/srcpkgs/keyd) 软件包由 [@Barbaross](https://gitlab.com/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](https://docs.qmk.fm/#/one_shot_keys) 修饰键等高级功能。虽然部分 X 工具提供类似功能，但据我所知，没有哪款能像 keyd 这样灵活。

## [kmonad](https://github.com/kmonad/kmonad)? 呢？

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

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

## 为什么 keyd 不实现功能 X？

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

# 贡献

请参阅 [CONTRIBUTING](CONTRIBUTING.md)。
IRC 频道：oftc 上的 #keyd