Passkey 创建/登录失败 - WebAuthn 问题排查

前置条件检查

Passkey 功能有硬前提，不满足直接不能用：

任何一个条件不满足，Passkey 都会直接失败。

创建 Passkey 失败

症状一：点击"创建 Passkey"后无反应

原因：系统没有正确检测到 KeePassDX 的凭证提供程序服务。

排查步骤：

1. 确认 KeePassDX 的凭证提供程序服务已开启（KeePassDX 设置里）
2. 确认系统设置里也选了 KeePassDX 作为凭证提供程序
3. 重启 KeePassDX 和目标网站
4. 如果还不行 → 重启手机（Android 14 的凭证提供程序服务有时需要系统级重启才生效）

症状二：弹出用户验证后又消失

原因：设备锁屏未设置 / 锁屏凭证临时失效。

排查步骤：

1. 确认手机确实设置了锁屏（PIN/图案/密码）
2. 在 Android 设置里重新验证锁屏凭证（输一次 PIN 确认没忘）
3. 确认生物识别（如果用）已正确登记

症状三：用户验证后报错"数据库无法打开"

原因：Passkey 创建需要 KeePassDX 数据库已解锁（或能解锁）。如果数据库：

• 还没打开且主密码输错了
• 密钥文件路径丢了
• 数据库文件损坏

都会导致 Passkey 创建失败。

Passkey 登录失败

症状一：网站没显示 Passkey 登录选项

原因：目标网站的浏览器不支持 Passkey / WebAuthn。

排查步骤：

1. 确认网站本身支持 Passkey（Google、GitHub、Microsoft、亚马逊等支持）
2. 用 Chrome（最新版）测试——Chrome 对 WebAuthn 支持最完善
3. 如果用的是其他浏览器（Firefox、三星互联网、国产浏览器），可能不支持

症状二：选 Passkey 后弹了 KeePassDX 但无法完成 UV

原因：用户验证（UV）流程卡住。

排查步骤：

1. 确认数据库打开时是否启用了 UV 模式
2. 如果禁用 UV 模式打开了数据库，某些网站（Relying Party）要求 UV 时会强制报错
3. 解决：关闭数据库 → 重新打开时启用 UV 模式 → 再试 Passkey 登录

症状三：登录时提示"不支持"

原因：Android 14 的 Passkey 协议版本不匹配 / 网站用了 Android 暂不支持的 WebAuthn 功能。

这种情况 KeePassDX 本身没问题，是 Android 系统或网站的 WebAuthn 实现问题。可以在 KeePassDX GitHub Issues 查是否有同类报告。

症状四：提示"域名不匹配"

原因：WebAuthn 的 Relying Party（RP）域名绑定检查失败——你可能在一个和原注册域名不同的路径/子域登录。

这是正确的安全行为——防止钓鱼。确认你在正确的网站上登录，不是伪装的钓鱼站。

降级处理

如果 Passkey 实在用不了，退回传统方式：

• 继续用该网站的密码 + OTP/2FA
• 不要因为 Passkey 折腾太久而影响日常使用
• 可以等 KeePassDX 新版本或 Android 版本升级后再试

查看日志

KeePassDX 设置 → 日志 → 找 "WebAuthn"、"Passkey"、"Credential Provider" 相关的 Error/Fatal 记录，提交到 GitHub Issues 时附上这些日志。