错误码与数据库查询 —— Cryptomator 官方错误库怎么用
遇到错误怎么办
Cryptomator 遇到意外错误时会弹一个红/黄色对话框，通常包含：
- 一段人类可读的错误描述（比如 "Could not unlock vault. File not found."）
- 一个内部错误码（比如
MASTERKEY_NOT_FOUND或类似代码） - 一个 "Error Handling" 或 "Report" 按钮
第一步：看错误码
错误码是定位问题的关键。它通常是一个大写的常量字符串，比如：
MASTERKEY_NOT_FOUND—— masterkey.cryptomator 找不到INVALID_PASSWORD—— 密码错误（不一定是真错了，也可能是 Recovery Key 输错）VAULT_CONFIG_MISSING—— vault.cryptomator 找不到FILESYSTEM_ERROR—— 文件系统底层报错CIPHER_ERROR—— 加密层报错
第二步：查官方错误库
docs.cryptomator.org 有一个 官方 Error Handling 页面（文档站可查） 页面，列出了所有已知错误码、触发条件、可能原因和解决方案。
也有一个 Common Errors 页面专门收集高频错误（比如 WinFsp 装不上、macOS Gatekeeper 阻止启动、Linux FUSE 组没加对等）。
第三步：搜社区
community.cryptomator.org 是官方社区论坛。把错误码 + 你的上下文（什么版本、什么系统、怎么触发的）放进去搜一遍——大概率有人已经遇到过同样的问题，有解决方案。
第四步：如果社区没答案
在社区发帖，提供：
- Cryptomator 版本号（Help → About 里看）
- 操作系统版本（Windows 10 / macOS 13 / Ubuntu 22.04 ...）
- Vault Format 版本（Format 7 还是 8）
- FUSE 驱动版本（如果用的是 FUSE 模式）
- 完整错误码和错误描述（直接复制粘贴，不要自己翻译）
- 复现步骤（你点了哪个按钮、做了什么操作触发的）
社区有 Skymatic 官方团队成员和资深用户常驻，响应速度通常不错。
高频错误速查
| 错误码 / 表现 | 最可能原因 | 怎么解决 |
|---|---|---|
| 提示 "Masterkey file not found" | masterkey.cryptomator 被删 / 损坏 / 云盘同步没完成 | 用 Recovery Key 重建（见恢复分组） |
| 解锁时报密码错，但你确认密码是对的 | 键盘布局变了（比如设密码时是英文布局、现在是中文布局） | 切回英文键盘布局再输密码 |
| Lock 时 "Device is busy" | 有进程占用虚拟盘文件 | 关掉所有打开虚拟盘的程序 + 等 30 秒 |
| macOS 上启动被 Gatekeeper 阻止 | Apple 安全机制（Cryptomator 不是 App Store 下载的） | 系统设置 → 隐私与安全 → 允许 |
| Linux 上报 "fuse: unknown option" | 用 FUSE 2 参数但系统是 FUSE 3 | 去掉 -o 后面的旧参数 |
| WebDAV 挂载后 Finder 里慢 | macOS WebDAV 原生实现性能差 | 换 FUSE-T |
1.16.0+ 的 EventView
Cryptomator 1.16.0 新增了 EventView——在解锁状态的保险库详情面板里可以看到一个事件日志，记录：
- 最近的解锁/锁定事件
- 哪个进程在访问保险库文件（对排查"谁在占用虚拟盘"特别有用）
- 同步冲突事件
- 加密层异常
如果 EventView 里已经有了事件记录，它本身就是定位问题的第一手信息。
系统日志在哪
Cryptomator 在不同系统上的日志位置：
| 系统 | 日志路径 |
|---|---|
| Windows | %APPDATA%\Cryptomator\logs\ |
| macOS | ~/Library/Application Support/Cryptomator/logs/ |
| Linux | ~/.local/share/Cryptomator/logs/ |
日志文件是纯文本，按日期命名。遇到复杂问题时，把日志文件里报错前后 10-20 行复制出来发帖会大大提高得到有用回复的几率。