KeyRemap (v1.0.0)

KeyRemap 是一款 macOS 原生键盘按键重映射工具。可把任意按键或组合键改成其他按键、直接屏蔽，或映射为一段常用文本；规则保存在本地，支持 Intel 与 Apple Silicon。

一、为什么要改键

Mac 的键盘很好用，但「好用」是苹果替你定义的。

Vim 用户每天要把左手小指伸到左上角去够 Escape；从 Windows 转过来的外接键盘，Alt 和 Command 的位置永远记反；Caps Lock 占着键盘上最黄金的位置，却几乎只用来误触发一整段大写；写代码时同一个邮箱、同一段签名、同一句常用回复，一天要敲十几遍。

系统自带的「修饰键」设置只让我们在 Caps Lock / ⌃ / ⌥ / ⌘ 这几颗键之间互换，或者把其中一颗设为「无操作」，再细就无能为力了。KeyRemap 想解决的正是这一层：让你按自己的习惯，逐颗定义键盘上任意按键的行为。

二、它能做什么

核心是「一条规则 = 一个触发键 + 一个动作」，动作有三种：

几个容易被忽略但很关键的细节：

• 组合键也能触发。不只是单键，⌃⌥K → Escape 这类组合同样可以录制。录的时候按住修饰键再按主键，松手后界面会稳定显示 ⌃⌥K，不会把修饰键弄丢。
• 严格修饰键匹配。默认只有「修饰键完全一致」时才触发。所以哪怕你把 C 映射成 D，⌘C 依然是复制，不会因为一个映射把整套系统快捷键搞坏。
• Caps Lock 特别处理。大写锁定状态由系统在事件链的更上游维护，只吞掉按键会出现「键变了、大写灯还亮着」的怪事。KeyRemap 会在改键后异步复位大写锁定状态。
• 规则细粒度可控。每条规则有独立开关，顶部还有一个总开关，菜单栏图标可以在不打开窗口的情况下一键暂停。

三、界面与三步上手

第 1 步：授权。 建议先把 .app 拖进 /Applications 再启动。窗口顶部会出现橙色提示条，点「请求授权」，到「系统设置 › 隐私与安全性 › 辅助功能」里勾选 KeyRemap；回到窗口，提示条消失，标题下方变成「正在后台拦截按键 · 全局生效」，映射立即生效。这是 macOS 对全局键盘事件拦截的硬性要求，不是 App 在要多余权限。

第 2 步：加规则。 点左下角「添加映射」，或者直接从「常用预设」里挑一条 —— 内置了 Caps Lock → Escape、→ Delete、→ F19（可被其他 App 识别）、→ 不响应 四种。首次启动也默认带一条 Caps Lock → Escape。

第 3 步：录制。 点左侧键帽，按下想改的那颗键即可（按住 ⌃⌥ 再按就是组合键）；点右侧键帽，选择要变成按键、屏蔽还是一段文本。底部会实时显示「N / N 条生效」。窗口右下角「⋯」里可以导入 / 导出配置、打开配置文件所在位置；右上角的齿轮菜单里则是「严格匹配修饰键」「开机自动启动」和系统权限设置的快捷入口。

四、几个真实用得上的场景

• Vim / Emacs / IDE 重度用户：Caps Lock → Escape，小指不用再横跨整个键盘。
• 外接键盘与跨平台：把 Windows 布局键盘的键位改成 macOS 肌肉记忆，不用在两套习惯之间来回切换。
• 误触重灾区：直接屏蔽 Caps Lock，或者映射到 F19 这种系统不占用的键，再交给其他自动化工具当「专属触发键」。
• 重复输入：邮箱、工号、客服常用语、代码片段，做成一个按键就行。
• 人体工学调整：把高频按键挪到小指够得着的位置，减少手腕和手指的反复移动。

五、实现上的几个讲究

KeyRemap 是 Swift + SwiftUI / AppKit 写的原生 App，不依赖浏览器内核或第三方运行时，最低支持 macOS 12，并编译成 arm64 + x86_64 通用二进制。

技术上有两点值得单独说：

就地改写事件，而不是合成新事件。 它在会话级事件流上挂了一个 head-insert 的 CGEventTap，命中规则时直接改写原事件的 keyCode / flags，再把原事件放行。这样不会产生「拦截 → 造一个新事件 → 新事件又被自己拦到」的回环，延迟也几乎可以忽略：

键盘 → IOHIDSystem → WindowServer → [KeyRemap 事件 Tap] → 目标 App
                                        ↑ 改写 keyCode / flags

配置只是一个本地 JSON 文件。 规则、总开关、严格匹配开关都写在 ~/Library/Application Support/KeyRemap/config.json，可以直接编辑、备份或纳入版本管理，不上传任何服务器。权限状态还会被自动观察：用户在系统设置里勾选辅助功能后，引擎会自己接管，不用重启 App。

注意事项与能力边界

• 需要辅助功能权限。ad-hoc 签名与文件路径绑定，每次重新打包后可能要在系统设置里取消勾选再勾一次；两个 .app 的 Bundle ID 不同，授权互相独立。
• 安全输入框不生效。密码框、锁屏、登录界面处于 secure input 状态，任何基于事件 tap 的工具都无法拦截，这是系统限制。
• 修饰键本身不能单独当触发键。⌘ / ⌥ / ⌃ / ⇧ 产生的是 flagsChanged 事件，和普通按键不在同一条链路；目前支持「普通按键 + 修饰键组合」。
• 把 Caps Lock 设为触发键会失去大小写切换，因为它的大写状态会被强制复位。想保留大写功能就别动这颗键。
• 当前为 ad-hoc 签名、未做公证，跨机器分发会被 Gatekeeper 拦截（右键 → 打开 可绕过）。

小结

改键这件事，门槛不该是「先学会写一份 Karabiner 配置」或者「装一个常驻后台的沉重工具」。KeyRemap 把范围收得很窄：打开窗口、按下要改的键、选一个结果，剩下的交给菜单栏里那个小图标。规则本地可导出、随时可暂停、不碰系统快捷键 —— 对大多数只想把 Caps Lock 换成 Escape、或者顺手屏蔽掉某个误触键的人来说，这样就够了。