故障排查：Mac 上保管库无法打开（iCloud 占位文件）

先准确读懂错误信息

桌面 KeePass App 会区分两种截然不同的失败情况，从措辞就能判断你遇到的是哪一种。以 KeePassXC 为例：

"Failed to read database file."（无法读取数据库文件）——App 根本拿不到文件的字节内容。这正是本指南要解决的占位文件问题。请继续往下读。

"Error while reading the database: Invalid credentials were provided" / "HMAC mismatch"（读取数据库时出错：提供的凭据无效 / HMAC 不匹配）——文件本身读取正常，是主密码、密钥文件或硬件密钥不对。这是另一类问题——请重新核对你的凭据。

为什么会这样：占位文件

为了释放磁盘空间，macOS 可能会悄悄把很少打开的本地文件替换成一个占位文件（Apple 称之为优化 Mac 储存空间；第三方同步客户端也有类似的「按需文件」功能）。Finder 中仍会显示文件名和完整大小，但内容只存在于云端。

正常情况下，打开占位文件会自动重新下载它。但这一静默的重新下载有时不会触发——于是所有尝试读取文件原始内容的 App（包括任何桌面 KeePass App）看到的都是一个无法读取的空文件。

你的 iPhone 不受影响，因为它保留了自己已完整下载的副本——这正是 Kakuremi 仍能打开保管库、而 Mac 却打不开的原因。

修复方法：强制下载文件

在 Finder 中，右键点按该 .kdbx 文件并选择立即下载（Download Now）（存放在 iCloud 中的文件旁会显示云朵图标）。等云朵图标消失后，再用桌面 App 重试。

如果 Finder 中没有这个选项，或者你更喜欢使用终端：

brctl download ~/Documents/path/to/vault.kdbx

等待几秒钟，然后用 ls -lO vault.kdbx 验证——输出中的 dataless 标志应该已经消失。此时保管库就能正常打开了。

仍然失败？查清文件夹由哪个服务管理

文件夹名称可能会误导你。开启 iCloud 的桌面与文稿同步后，~/Documents 和 ~/Desktop 下的所有内容都由 iCloud 管理——即便某个文件夹挂着你多年前用过的另一款同步工具的名字。

要查看文件实际归哪个提供方管理，运行：

fileproviderctl evaluate ~/Documents/path/to/vault.kdbx

输出中出现 Ubiquitous… 表示由 iCloud 管理——按第 3 步的方法使用 Finder 或 brctl。如果输出中显示的是某个第三方提供方，请确认该客户端已安装、正在运行且已登录；同步客户端已被卸载的占位文件会一直无法读取，直到重新装回该客户端（或直接从该服务获取文件）为止。

防止问题再次发生

在 Finder 中，右键点按保管库文件（或其所在文件夹）并选择保留下载项（Keep Downloaded）。macOS 将不再清除它的本地内容，桌面 App 也就始终能读到真实的文件字节。

或者，关闭系统设置 → Apple ID → iCloud → 优化 Mac 储存空间——代价是所有 iCloud 文件都会占用更多磁盘空间。

每个保管库只使用一个同步服务。两个客户端同步同一个文件夹，不仅难以判断文件归谁管理，还会招致 iCloud Drive 指南中描述的静默覆盖冲突。