使用文档

入门指南

Karabiner-Elements 是一款功能强大且稳定的 macOS 键盘定制工具。无论你是想简单地将 Caps Lock 改造为 Esc 键，还是希望构建带有条件触发的复杂按键规则，Karabiner-Elements 都能以最直观的方式满足需求。本节将带你完成从安装到第一次配置的完整流程。

安装完成后，应用会自动驻留在菜单栏，提供配置入口与状态指示。所有配置变更实时生效，无需重启应用或系统。配置文件自动保存于用户目录下，支持版本管理与跨设备同步。建议首次使用时先熟悉 Simple Modifications 面板，再逐步探索 Complex Modifications 的高级能力。

核心提示：Karabiner-Elements 与 Karabiner-EventViewer 是两个独立应用，前者负责配置管理，后者负责事件调试。两者需分别授予输入监控权限。

Simple Modifications 简单映射

Simple Modifications 是 Karabiner-Elements 最基础也最常用的功能，提供图形化的按键重映射界面。用户无需编写任何代码，通过下拉菜单即可完成单个按键到另一个按键的映射。该功能适合实现诸如 Caps Lock 改造、方向键重排、功能键互换等常见需求。

使用方法非常直观：打开 Karabiner-Elements 主界面，切换到 Simple Modifications 标签页，点击左下角的 Add Item 按钮，在 Target 列选择要重映射的源按键，在 From 列选择目标按键，配置立即生效。每个设备可独立配置不同的映射方案，互不影响。若需重置某个映射，点击对应行的 Trash 图标删除即可。

需要注意，Simple Modifications 仅支持一对一的按键映射，无法实现条件触发或组合键。若需要更复杂的逻辑（如长按短按区分、修饰键组合、按键序列识别等），请使用 Complex Modifications 功能。

Complex Modifications 复杂规则

Complex Modifications 是 Karabiner-Elements 的核心引擎，支持基于条件的按键重映射规则。每条规则由一个或多个 manipulator 组成，每个 manipulator 定义了源按键事件（from）、目标按键事件（to）、以及可选的触发条件（conditions）。

Complex Modifications 提供两种添加规则的方式：导入社区规则与手动编写 JSON 规则。社区规则库（ke-complex-modifications.pqrs.org）提供了超过 500 个经过验证的预设方案，涵盖 Vim 模式、Emacs 绑定、Hyper 键改造、防误触等数十个分类。手动编写规则则可实现任意复杂的按键逻辑，是高级用户的首选。

规则的典型结构

每条 Complex Modification 规则包含 description（描述）、manipulators（操作列表）两个字段。每个 manipulator 至少包含 type、from、to 三个字段。可选字段包括 to_if_alone（单独按下时触发）、to_if_held_down（长按时触发）、conditions（触发条件）、parameters（参数）等。这种灵活的结构支持实现几乎任意复杂的按键逻辑。

{
  "description": "Change escape to escape + left_control",
  "manipulators": [
    {
      "type": "basic",
      "from": { "key_code": "escape" },
      "to": [
        { "key_code": "escape",
          "modifiers": ["left_control"] }
      ]
    }
  ]
}

设备管理

Karabiner-Elements 提供完善的设备级配置能力。在 Devices 标签页中，系统会自动列出所有已连接的键盘设备，包括内置键盘、USB 外接键盘、蓝牙键盘等。每个设备可以拥有独立的 Simple Modifications 映射方案，互不干扰。

常见的设备级配置场景包括：为 Windows 布局的外接键盘交换 Alt 与 Command 键位置；为 HHKB 等紧凑键盘补全方向键；为机械键盘设置不同的延迟与重复速率；当外接键盘连接时自动禁用内置键盘避免误触。所有设备识别基于厂商 ID 与产品 ID，精确可靠。

此外，Karabiner-Elements 还支持为特定设备忽略系统级快捷键拦截，这在游戏场景或专业软件中尤为有用。设备拔插时配置自动切换，无需任何手动操作。

Profile 多配置管理

Profiles 功能允许用户创建多套独立的配置方案，并快速切换。每个 Profile 包含完整的 Simple Modifications、Complex Modifications、Devices 配置，互不影响。典型用法包括创建办公模式、编码模式、游戏模式等不同场景的专属配置。

切换 Profile 的方式有三种：通过菜单栏图标下拉菜单、通过全局快捷键、通过命令行工具。菜单栏图标的下拉菜单会显示当前活跃的 Profile，并以对勾标记。Profile 之间切换瞬时完成，无需重启应用。所有 Profile 信息存储在同一个 karabiner.json 文件中，便于备份与迁移。

Profile 还支持导入导出功能。在 Misc 标签页可以导出当前所有 Profile 为 JSON 文件，方便团队共享或跨设备同步。导入时只需选择对应的 JSON 文件即可覆盖或合并现有配置。

EventViewer 事件查看器

Karabiner-EventViewer 是 Karabiner-Elements 的配套调试工具，独立于主应用运行。它实时显示所有键盘事件，包括按键按下、释放、修饰键状态变化、设备切换等。对于开发复杂规则或排查配置问题的用户来说，EventViewer 是不可或缺的利器。

EventViewer 提供三个主要视图：Main 显示原始按键事件、Modify 显示经过 Karabiner-Elements 处理后的事件、Extra 显示修饰键状态与设备信息。通过对比 Main 与 Modify 视图，可以直观验证配置规则是否按预期工作。

使用 EventViewer 时，建议先在 Main 视图中按下目标按键，确认 key_code 与修饰键组合正确捕获；然后切换到 Modify 视图，验证映射后的输出事件是否符合预期。这种"先观察、再配置、再验证"的工作流可以大幅提升复杂规则的开发效率。

JSON 配置文件详解

所有 Karabiner-Elements 的配置最终都存储在 ~/.config/karabiner/karabiner.json 文件中。这个纯文本 JSON 文件包含了 Profiles、Simple Modifications、Complex Modifications、Devices 等所有配置信息。理解该文件的结构对于高级用户编写复杂规则、进行版本管理、团队共享配置至关重要。

文件结构顶层包含 profiles 数组，每个 Profile 是一个独立配置单元，包含 name、parameters、simple_modifications、complex_modifications、devices、virtual_keyboard、fn_function_keys 等字段。建议将此文件纳入 dotfiles 版本管理，配合 Git 可以追踪配置变更历史，并在多台设备间同步。

{
  "profiles": [
    {
      "name": "Default",
      "selected": true,
      "simple_modifications": { /* ... */ },
      "complex_modifications": { /* ... */ },
      "devices": [ /* ... */ ],
      "fn_function_keys": { /* ... */ },
      "virtual_keyboard": { /* ... */ }
    }
  ]
}

更新日志

Karabiner-Elements 保持活跃的迭代节奏，新版本通常每月发布一次。以下是近期主要版本的更新要点，完整更新日志请访问 GitHub Releases 页面。

常见问题

以下是用户最常遇到的问题解答。如果你的问题未在此列表中，请访问 GitHub Issues 页面搜索或提交新问题。

故障排查

遇到问题时，请按以下顺序排查。大部分常见问题都可以通过授权权限或重启应用解决。

• 配置不生效：检查 Karabiner-Elements 是否在运行，菜单栏图标是否显示。前往系统设置的隐私与安全性 → 输入监控，确认权限已授予。尝试退出并重新启动应用。
• macOS 升级后失效：macOS 大版本升级可能重置输入监控权限。前往系统设置 → 隐私与安全性 → 输入监控，先关闭再重新开启 Karabiner-Elements 开关，然后重启应用。
• "Device is ignored temporarily" 警告：这通常发生在系统休眠或设备拔插时。Karabiner-Elements 会自动恢复，无需手动干预。若持续显示，请重启应用。
• Caps Lock LED 不亮：Apple 键盘的 Caps Lock LED 由硬件控制，可能与软件映射冲突。在 Devices 中将 Treat Caps Lock LED as functional LED 选项开启即可解决。
• 三键组合无法触发：某些键盘硬件限制同时按下的按键数量。可使用 EventViewer 验证按键事件是否被正确捕获。若事件未触发，需更换支持 N-Key Rollover 的键盘。