# 诊断与恢复

> 诊断页上的每项检查及其修复方法、Capslock 如何归还 Caps Lock，以及如何在终端中恢复。

---

LLMS 索引： [llms.txt](/zh/llms.txt)

---

「诊断」页运行一组检查，并为每一项失败的检查给出编号的修复步骤，大多数修复就是同一行上的
一个按钮。「刷新」会重新运行所有检查。

## 检查项 {#checks}

| 检查 | 正常 | 失败时 |
| --- | --- | --- |
| Caps Lock 映射 | Caps Lock 已就绪 | 未设置、被其他工具占用或无法读取。点「重新启用」或「恢复 Caps Lock」。 |
| F18 | F18 空闲 | 其他工具在使用 F18。移除那条改键后点「重新启用」。 |
| Karabiner-Elements | 未检测到，或无冲突 | 有规则使用 Caps Lock 或 F18，见 [Karabiner](/zh/docs/start/karabiner/#resolve)。 |
| 崩溃恢复 | 无需恢复 | 上次没有正常退出，已在启动时清理；或另一个 Capslock 正在运行。 |
| 辅助功能 | 已授权 | 点「打开辅助功能设置」「重新检查」或「重置并重新请求」。 |
| 发送按键 | 已允许 | 随辅助功能权限一并授予。点「请求权限」「重新检查」或「重置并重新请求」。 |
| 读取键盘 | 正在读取键盘 | macOS 停止了事件钩子。点「重新启用」或「全部松开」。 |
| 安全输入 | 关闭 | 密码输入框或终端的「安全键盘输入」会对所有应用隐藏按键。Capslock 从不关闭它；请关闭该输入框或选项。 |
| Caps Lock 按键 | 已收到 | 按一次 Caps Lock，然后点「刷新」。 |
| 配置 | 有效 | 文件无法读取。点「显示配置文件夹」，修复或替换它。 |
| 签名 | 有效 | 开发版本。 |
| 更新 | 已启用 | 此版本不会自动更新，请从官网下载新版本。 |

「重置并重新请求」会清除 Capslock 的辅助功能和发送按键授权记录并重新请求。当系统设置显示
Capslock 已获授权、检查却仍然失败时使用它；用不同的构建替换应用后可能出现这种情况。

## 拿回 Caps Lock {#recovery}

| 操作 | 作用 |
| --- | --- |
| 「暂停」 | 松开 Capslock 按住的一切，把 Caps Lock 还给 macOS，并在核对系统映射后显示「已暂停，Caps Lock 一切如常。」 |
| 「全部松开」 | 松开 Capslock 正在按住的所有按键、修饰键和鼠标按键，但不暂停。按键像是卡住时使用。 |
| 「恢复 Caps Lock」 | 暂停，并恢复 Capslock 启动之前的按键映射，然后报告是否核验成功。 |
| 「退出 Capslock」 | 在退出之前做与「暂停」相同的事。 |

Capslock 只移除它自己添加的内容，其他工具的改键保持不变。

### Capslock 意外停止时 {#crash}

当 Capslock 接管 Caps Lock 时，应用内的一个小助手会盯着它。如果 Capslock 崩溃或被强制
退出，助手会松开它按住的按键，并把按键映射恢复原状。下次启动时，Capslock 会先再检查一遍，
诊断页也会注明上次没有正常退出。

在必要时，Capslock 也会主动让出：当 macOS 不再允许它读取键盘、其他应用修改了系统按键映射，
或出现了 Karabiner 规则时，它会停止并归还 Caps Lock，而不是去争抢这个键。睡眠唤醒后，它会
重试几次再报告错误。新接入的键盘也会获得映射。

### 在终端中恢复 {#cli}

如果 Caps Lock 仍然表现异常，先退出 Capslock，再运行：

```bash
/Applications/Capslock.app/Contents/MacOS/Capslock --restore-original-caps-lock
```

它会恢复上一次会话之前的映射，不做任何无法核验的改动；Capslock 仍在运行时它会拒绝执行。
诊断页会按你的实际安装路径显示同一条命令，并附带「拷贝」按钮。

> [!WARNING] 不要手动清空映射
> `hidutil property --set '{"UserKeyMapping":[]}'` 会删除所有工具的改键，而不只是 Capslock 的。

## 导出诊断报告 {#export}

「导出…」会保存 `Capslock-Diagnostics.zip`，其中包含检查结果和近期日志的脱敏副本。它从不
包含你输入的内容、剪贴板、Shell 命令及其输出，也不包含你的配置。报告问题时请附上它。

---

反链：

- [常见问题](/zh/docs/reference/faq/)
- [卸载](/zh/docs/reference/uninstall/)
- [安装与首次运行](/zh/docs/start/install/)