从一个粘贴失效的 Bug 深入 Linux 键盘事件栈

从 GNOME 迁移到 KDE Plasma/Wayland 后，用 xremap 把 Alt+V 映射成 Ctrl+V，在 Brave 浏览器的文本框里失效，但地址栏正常。同样的配置在 GNOME 下运行了数月毫无问题。

这个现象让人困惑：窗口识别正确，权限配置正确，日志无报错，其他应用一切正常——唯独 Brave 文本框不响应。排查过程涉及 Linux 输入子系统、Wayland 协议、合成器差异、Chromium 架构，以及一个一行配置的最终解法。

一、Linux 键盘事件的完整旅程

理解这个问题，首先要清楚一次按键从硬件到应用的完整路径。

1.1 evdev 层：内核与用户空间的边界

当你按下一个键，键盘固件产生扫描码（scancode），内核驱动将其转换为 evdev 事件，写入 /dev/input/eventN：

EV_KEY  KEY_LEFTALT  1   # press
EV_SYN  SYN_REPORT   0
EV_KEY  KEY_V        1   # press
EV_SYN  SYN_REPORT   0
EV_KEY  KEY_V        0   # release
EV_SYN  SYN_REPORT   0
EV_KEY  KEY_LEFTALT  0   # release
EV_SYN  SYN_REPORT   0

每个事件包含三个字段：类型（type）、编码（code）、值（value）。EV_SYN 是同步信号，标志着一组原子事件的结束。注意：evdev 这一层只有原始的 keycode，没有任何"修饰键状态"的概念，那是上层的工作。

1.2 xremap 的工作层：uinput 虚拟设备

xremap 通过 uinput 内核模块创建一个虚拟输入设备。它从真实键盘的 evdev 节点读取原始事件，按照配置规则变换后，写入虚拟设备。整个过程对 Wayland 合成器完全透明——合成器看到的是虚拟设备发出的事件，不知道中间经过了一层变换。

xremap 的配置分两个阶段处理：

modmap：纯粹的 key-to-key 映射，在硬件 keycode 层面操作。例如：

KEY_LEFTALT: KEY_LEFTMETA   # 物理 Alt → Super
KEY_LEFTMETA: KEY_LEFTALT   # 物理 Super → Alt

keymap：组合键映射，在 modmap 变换之后的键值上匹配。例如：

Win-v: ctrl-v   # modmap 后的 Win（即物理 Alt）+ v → Ctrl+v

1.3 Wayland 合成器：modifier 状态机

Wayland 合成器（KWin、Mutter）从 evdev 或 uinput 读取事件后，维护一个 XKB 状态机来跟踪当前的修饰键状态。XKB（X Keyboard Extension）是一套键盘描述语言，定义了 modifier 的语义：

depressed modifiers = 当前物理按下的修饰键的位掩码
latched modifiers   = 已锁存但未释放的修饰键（如 Sticky Keys）
locked modifiers    = 已锁定的修饰键（如 Caps Lock）

每当 modifier 键的状态发生变化，合成器会向焦点窗口发送 wl_keyboard.modifiers 事件：

wl_keyboard.modifiers(serial, mods_depressed, mods_latched, mods_locked, group)

关键在于：modifier 状态是异步通知的，客户端需要自己维护一份 XKB 状态副本来解读后续的 key 事件。

二、问题复现：wev 日志的解读

用 wev（Wayland event viewer）在受影响的文本框中按 Alt+V，得到以下输出：

[wl_keyboard] key: key: 37; state: 1 (pressed)
              sym: Control_L (65507), utf8: ''
[wl_keyboard] modifiers:
              depressed: 00000044: Control Mod4    ← Control + Super 同时在按
              latched: 00000000
              locked: 00000000
[wl_keyboard] key: key: 133; state: 0 (released)
              sym: Super_L (65515), utf8: ''
[wl_keyboard] modifiers:
              depressed: 00000004: Control          ← Super 才刚释放
              latched: 00000000
              locked: 00000000
[wl_keyboard] key: key: 55; state: 1 (pressed)
              sym: v (118), utf8: ''               ← v 按下时 Mod4 已清

等等，这个日志看起来是正确的——v 按下时 depressed 只有 Control，Mod4 已经释放了。

但这是 wev 窗口里观察到的结果。wev 是一个普通 Wayland 客户端，它收到的事件是合成器按顺序分发的，modifier release 确实在 v press 之前到达。

问题发生在 Brave 浏览器里，Brave 打开了 chrome://keyboard-internals 让我们可以直接观察它收到的事件序列——它看到的是 Ctrl+Super+V，而不是 Ctrl+V。

这两者之间的差异，揭示了这个 Bug 的真正所在。

三、根因：合成器事件分发的时序竞争

3.1 uinput 注入的事件序列

xremap 在处理 Win-v → ctrl-v 时，需要：

1. 注入 Control_L press
2. 释放原始的 Super_L（消费掉原始键）
3. 注入 v press
4. 注入 v release
5. 释放 Control_L

实际通过 uinput 写入的事件流大致是：

EV_KEY Control_L 1   (press)
EV_SYN
EV_KEY Super_L   0   (release)  ← xremap 发出 Super 的 release
EV_SYN
EV_KEY v         1   (press)
EV_SYN

3.2 合成器的处理流程

KWin 从 uinput 设备读取这些事件，用 libinput 处理后，更新内部 XKB 状态并分发给焦点窗口。关键问题在于：

XKB 状态更新和 wl_keyboard.modifiers 的发送是否在 v press 之前完成？

合成器的事件处理通常在一个 event loop 里，大致流程是：

读取 evdev 事件 → libinput 处理 → 更新 XKB 状态 → 发送 wl_keyboard 事件

在理想情况下，Super_L release 处理完毕（XKB 状态里 Mod4 清掉）之后，再处理 v press。但这里有一个微妙的问题：

xremap 通过 uinput 写入事件时，是批量写入的——Control_L press、Super_L release、v press 几乎同时写入内核缓冲区，两个 EV_SYN 之间的间隔可能只有几微秒。合成器在同一个 event loop tick 里一次性处理这一批事件时，modifier 状态更新和 key 事件分发的顺序取决于合成器的具体实现。

3.3 Mutter vs KWin 的关键差异

这里有一个决定性的证据：GNOME 的 Mutter 在 2014 年合并了一个 patch，专门处理这个问题：

wayland-keyboard: Send modifiers after the key event

The key event should be interpreted by clients with the modifier state
as it was before the event itself just as in X11 input events.
Achieving this in wayland is a matter of sending the key event first
and the modifiers after (if needed).

This isn't really specified in the wayland protocol but it matches
weston's behavior and should avoid corner cases in clients.

Mutter 的策略是：先发 key 事件，再发 modifier 变化通知。也就是说，当 Super_L release 到来时：

• Mutter 先把 key release 事件发给客户端
• 然后再发 modifier 状态变化

这样客户端在处理 Super_L release 时，modifier 状态还是旧的（Super 还在按）；在处理后续 v press 时，收到的 modifier 快照里 Mod4 已经清掉了。

KWin 没有这个特殊处理。在 KWin 下，Super_L release 导致的 modifier 状态变化和 v press 的事件分发顺序不确定（或者说，对于批量写入的 uinput 事件，modifier 状态可能在 v press 之前就更新了，但客户端收到 modifier 通知的时机与 key 事件的时机产生了竞争）。

结果是：Brave 在某些时序下收到 v press 时，它的本地 XKB 状态副本显示 depressed = Control | Mod4，即 Ctrl+Super+V。

四、为什么只有 Brave 受影响

4.1 Qt/GTK 对 modifier 的宽松处理

Qt 在处理快捷键时，会对 modifier mask 做一定的过滤。QKeySequence 匹配时，会忽略一些"无关"的修饰键（特别是 Mod4/Super，在大多数应用场景下不是有意义的修饰键）。GTK 的行为类似。

这意味着即使这些 toolkit 收到了 Ctrl+Super+V，它们仍然能匹配到 Ctrl+V 对应的 paste action。

4.2 Chromium 的严格匹配：ui::KeyEvent

Chromium 在 Wayland 下使用自己的 Ozone 平台层处理输入，其核心是 ui::KeyEvent。Chromium 的事件处理链大致是：

Wayland 事件 → OzonePlatformWayland → WaylandKeyboard
             → ui::KeyEvent → AcceleratorManager → 快捷键匹配

Chromium 的 AcceleratorManager 对 modifier 做精确匹配：快捷键 Ctrl+V 对应的 modifier mask 是 EF_CONTROL_DOWN，当实际收到的 event flags 是 EF_CONTROL_DOWN | EF_COMMAND_DOWN（Super 对应 Command），两者不等，paste 动作不触发。

4.3 为什么地址栏（Omnibox）能用

Brave 的地址栏（Omnibox）是 Chromium 里一个特殊的输入控件，它有独立的键盘事件处理路径，对修饰键的匹配比普通 <textarea> 更宽松——Omnibox 会接受带额外修饰键的输入，只要核心键值匹配，就执行对应操作。这是 Chromium 为了支持各种操作系统快捷键习惯而做的兼容性处理。

4.4 为什么 GNOME 下没问题

如上文所述，Mutter 的事件发送顺序保证了客户端在处理 v press 时，看到的 modifier 状态是正确的。KWin 没有这个保证，所以 modifier 残留只在 KDE 下出现。

五、诊断过程

排查这类问题，工具链至关重要。

第一步：确认窗口识别

xremap --watch=config ~/.config/xremap/config.yml

输出：

active window: caption: '...', class: 'brave-browser'

窗口识别正确，排除 application filter 匹配失败。

第二步：确认 uinput 权限

ls -la /dev/uinput   # crw-rw----+ 1 root input
groups | grep input  # 用户在 input 组

权限正常，排除注入失败。

第三步：用 wev 观察实际事件

wev

在 wev 窗口里按 Alt+V，看到 Control_L press → Super_L release → v press，序列正确。但这是 wev 窗口的视角，不代表 Brave 看到的相同。

第四步：在 Brave 内部验证

打开 chrome://keyboard-internals，按 Alt+V，看到 Brave 接收到的 modifier 是 Ctrl+Super。确认问题：Brave 在 v press 时刻看到了 Mod4 残留。

六、解决方案：keypress_delay_ms

xremap 官方文档（以及 issue #179）记录了这个已知问题：

Some applications have trouble understanding synthesized key events, especially on Wayland. keypress_delay_ms can be used to workaround the issue.

keypress_delay_ms: 20   # 在顶层配置，全局生效

modmap:
  - name: Global
    remap:
      KEY_LEFTALT: KEY_LEFTMETA
      KEY_LEFTMETA: KEY_LEFTALT
      # ...

keymap:
  # ...

keypress_delay_ms 的作用是在每个注入的 key 事件之间插入一个延迟。在我们的场景下，这意味着：

Control_L press  → 等待 20ms
Super_L release  → 等待 20ms  ← 合成器有充分时间处理这个 release 并通知客户端
v press          → Brave 收到时，Mod4 已经清掉了

20ms 是一个经验值。合成器的 event loop 通常以 60Hz（16.7ms/frame）或更高频率运行，20ms 足以保证 modifier release 被完整处理。实践中 10ms 通常也够，取决于系统负载。

这个方案的代价是轻微的输入延迟感——每次触发 keymap 规则时，按键响应会有约 20ms 的延迟。对于复制粘贴这类操作，这个延迟几乎不可感知。

七、更深层的思考

7.1 Wayland 协议的设计取舍

Wayland 协议本身并没有规定 modifier 事件和 key 事件的相对顺序。Wayland Book 里只说：

The modifiers event includes masks of the depressed, latched, and locked modifiers.

顺序是"implementation defined"。Mutter 选择了"key 先于 modifier 通知"的策略，weston（参考实现）也采用了同样的策略，但 KWin 的行为不同。这是 Wayland 生态里一个典型的合成器行为碎片化问题。

7.2 X11 为什么没有这个问题

在 X11 里，每个 XKeyEvent 结构体直接携带了 state 字段（modifier 位掩码），它反映的是该键事件发生时的 modifier 状态，是原子的，不存在异步通知的竞争问题。

typedef struct {
    int type;           /* KeyPress or KeyRelease */
    unsigned long serial;
    Bool send_event;
    Display *display;
    Window window;
    ...
    unsigned int state; /* key or button mask */  ← modifier 内联在事件里
    unsigned int keycode;
    ...
} XKeyEvent;

Wayland 将 modifier 状态拆分成独立的异步消息，在语义上更清晰，但引入了时序依赖。

7.3 uinput 注入的固有局限

xremap 通过 uinput 在内核层面注入事件，这是目前在 Wayland 下实现全局键盘重映射的唯一可行方案（Wayland 的安全模型不允许用户态程序拦截其他应用的键盘输入）。但 uinput 注入的事件和真实硬件事件在时序上有本质差异：

真实硬件：键盘固件保证 modifier 按下和字符键按下之间有物理时间间隔（人的手指按键速度）

uinput 注入：所有事件几乎同时写入，依赖合成器能正确处理"同一批次"内的事件顺序

keypress_delay_ms 本质上是在用人工延迟模拟这个物理时间间隔，让合成器的状态机有时间"追上"事件流。

总结

问题的本质是：uinput 批量注入事件导致 modifier release 和 key press 之间没有时间间隔，KWin 在分发事件时 modifier 状态尚未更新到客户端，Chromium 的严格 modifier 匹配导致快捷键失效。

Mutter 通过"key 事件先于 modifier 通知"的策略规避了这个问题，KWin 没有，所以同样的配置从 GNOME 迁移到 KDE 后才暴露了这个 Bug。

最终解法一行配置：

keypress_delay_ms: 20

用 20ms 的人工延迟换取 modifier 状态的正确传播，代价极小，效果稳定。