通行密钥故障排除：通行密钥问题与错误解决方案

1. 简介#

根据 FIDO 联盟 2024 年身份验证晴雨表的数据，目前全球前 100 大网站中有 20% 支持通行密钥，全球 53% 的消费者已在至少一个帐户上启用了通行密钥。Amazon、WhatsApp、Coinbase、TikTok、Facebook、LinkedIn 和 X/Twitter 都自 2023 年起发布了相关支持。

W3C WebAuthn Level 3 规范定义了一系列 DOM 异常，但为了避免隐私泄露，根据 W3C 隐私注意事项，浏览器故意将大多数失败（用户取消、超时、不合格的身份验证器）归为通用的 NotAllowedError。许多依赖方也定义了它们自己的错误消息，因为除了 FIDO 联盟的 UX 指南之外，并没有太多被证明行之有效的最佳实践。本指南将最常见的面向消费者的表述映射到明确的原因和实用的解决方案，并附有初始版本以及最新的 iOS 和 Android 版本的屏幕截图。

如果您的设备上出现“google 通行密钥无法使用”（google passkey not working），首先要检查浏览器、操作系统和 Google Play 服务是否均为最新版本，因为大多数回退问题都会在一两个版本内得到修复。

2. 通行密钥是如何工作的？#

通行密钥是基于 WebAuthn API 以及底层 FIDO 联盟 CTAP 2.2 规范的无密码凭据。W3C 于 2019 年 3 月标准化了 WebAuthn Level 1，2021 年 4 月标准化了 Level 2，并在 2024 年标准化了 Level 3。根据 FIDO 联盟 Authenticate 2024 会议，到 2024 年第四季度，各主要生态系统中已注册的凭据数量达到了约 10 亿个。

设备在注册时会生成唯一的密钥对。只有公钥会发送到依赖方，而私钥保留在安全飞地、TPM 或 TEE 中。登录时，服务器发送质询，设备使用 Face ID、Touch ID 或 Windows Hello 解锁私钥，对质询进行签名并返回签名。依赖方使用公钥对其进行验证。

由于私钥永远不会离开设备，因此网络钓鱼和密码重用不再是有效的攻击媒介。从用户的角度来看，整个流程就是一次简单的生物识别提示。

3. 通行密钥的要求#

3.1 iOS 或 macOS#

已启用 iCloud 钥匙串：

iCloud 钥匙串是 Apple 设备上凭据的存储位置，并且随 iOS 16、iPadOS 16 和 macOS Ventura 13 或更高版本一起发布。根据 Apple 的开发者仪表板，Apple 在 2024 年初报告了约 22 亿台活跃设备，其中超过 90% 运行 iOS 16 或更高版本。要启用 iCloud 钥匙串，请导航到您设备的设置，选择您的 Apple ID，进入 iCloud 然后启用 iCloud 钥匙串（在此处阅读更多内容）。根据 Apple 开发者文档，启用了钥匙串的 iCloud 帐户会被强制要求使用 MFA。

需要 iOS 16 或 macOS Ventura：

iOS 16 于 2022 年 9 月 12 日发布，macOS Ventura 13 于 2022 年 10 月 24 日发布。在 iOS 18 上，存储位置移至专用的密码应用中，这就是为什么有些提示现在写的是“密码”而不是“iCloud 钥匙串”。根据 Apple 支持文档，使用较旧系统版本的用户根本无法创建或使用通行密钥。

3.2 Windows#

Windows Hello 设置：

在 Windows 10 和 Windows 11 设备上创建或使用通行密钥需要使用 Windows Hello。根据 Microsoft 的 Windows 通行密钥文档，Windows 11 build 22631（2024 年 11 月）发布了原生通行密钥 UI，Windows 11 25H2（2025 年 11 月）增加了对 1Password 和 Bitwarden 等第三方通行密钥管理器的支持。Windows Hello 接受指纹、面部扫描或 6 位 PIN 码。您可以在“设置 > 帐户 > 登录选项”下进行配置（在此处阅读更多内容）。

3.3 Android#

Android 9 或更高版本：

Android 9（Pie）于 2018 年 8 月 6 日发布，它是凭据管理器 API（Credential Manager API）的最低版本要求。根据 Android 分发仪表板，在 2026 年，大约 95% 的活跃 Android 设备运行的是 Android 9 及更高版本。较旧的版本根本无法使用通行密钥，因为它们缺少 StrongBox Keymaster 和凭据管理器。

Google Play 服务已更新：

凭据管理器要求 Google Play 服务的版本为 23.40 或更高。Google Play 服务大约每 4 到 6 周更新一次，大多数关于“google 通行密钥无法使用”的问题都可追溯到过时的版本。请在“设置 > 应用”下更新 Google Play 服务和系统 WebView，然后重试。

在所有平台上，请确保浏览器为最新版本。Safari、Chrome 和 Edge 大约每周都会发布稳定版更新，大多数回退问题都会在一两个版本内得到修复。

4. 常见的通行密钥错误、原因及故障排除#

我们跟踪了跨 iOS、Android 和 Windows 客户端的大约 15 种常见错误模式，这些错误加起来占了主要依赖方观察到的大部分消费者支持工单。接下来的 6 个部分按根本原因对这些错误进行分组：iCloud 钥匙串和 Apple 密码应用、无可用凭据、二维码和跨设备流程、Windows 专属问题、Android 专属问题以及通用的 WebAuthn 或浏览器存储区。

每个条目都包含原始版本以及最新的 iOS 版本和 Android 凭据管理器版本的屏幕截图、最可能的原因以及对其他人有效的解决方案。在适当的地方，条目还会引用 W3C WebAuthn Level 3 规范、FIDO 联盟规范或来自 Apple、Microsoft 和 Android 凭据管理器的相关平台文档。

5. iCloud 钥匙串和 Apple 密码应用错误#

本组涵盖了 Apple 设备在未正确设置 iCloud 钥匙串时显示的两个错误。这两者都是由系统直接呈现的，而不是依赖方。根据 Apple 开发者文档，iCloud 钥匙串是在 iOS 16、iPadOS 16 或 macOS Ventura 13 及更高版本上使用通行密钥的硬性要求。在 iOS 18 上，存储移至新的密码应用，因此表述发生了变化。

错误消息：要存储通行密钥，您需要启用 iCloud 钥匙串。您可以在系统设置的 Apple ID 窗格中启用钥匙串 (To save a passkey, you need to enable iCloud Keychain. You can enable Keychain in the Apple ID pane of System Settings)#

在最新的 iOS 上，表述变为“要使用通行密钥，您需要启用 iCloud 钥匙串”，并且路径重命名为设置 > Apple 帐户 > iCloud > 密码和钥匙串：

• 原因： iCloud 钥匙串（Apple 设备上的凭据存储位置）未启用。
• 解决方案： 在系统设置的 Apple ID 窗格中（或在 iOS 18 上的“设置 > Apple 帐户 > iCloud > 密码和钥匙串”中）启用 iCloud 钥匙串。请确保其在您的设备之间同步，否则凭据将只存在于本地。

错误消息：找不到匹配的通行密钥 / 您的 iCloud 钥匙串中没有保存匹配的通行密钥 (There are no matching passkeys / There are no matching passkeys saved in your iCloud Keychain)#

在最新的 iOS 上，该提示现在印有新密码应用的品牌标记，内容为“在密码中未存储匹配的通行密钥...”：

• 原因： 用户尝试使用未存储在当前设备的 iCloud 钥匙串中的凭据进行登录，或者设备之间的同步已断开。
• 解决方案： 确认在同一个 Apple ID 使用的所有 Apple 设备上都启用了 iCloud 钥匙串。如果凭据存在于另一部 iPhone 或 Mac 上，但当前设备上没有，请通过关闭然后再打开 iCloud 钥匙串强制同步，然后重试登录。如果完全没有凭据，请从依赖方的帐户设置中注册一个新的。

6. 无可用通行密钥和已存在错误#

当用户期望的凭据不在当前设备上、已被注册或已在一侧删除但在另一侧未删除时，就会出现这些错误。WebAuthn 属性 AllowCredentials 和 excludeCredentials 在服务器端驱动了大部分此类行为。

错误消息：没有可用的通行密钥。此设备上没有任何用于该依赖方的通行密钥 (No passkeys available. There aren't any passkeys for Relying Party on this device)#

在 Android 上，Google Play 服务也会显示同样的错误：“无可用通行密钥。此设备上没有任何用于 <依赖方> 的通行密钥”，并带有一个“使用不同设备”的后备选项：

• 原因： 当前设备上没有匹配的凭据，且 WebAuthn 服务器不允许任何跨平台身份验证器。当用户删除了本地凭据但服务器仍然期望使用它时，也会出现相同的错误消息。
• 解决方案： 验证设备上是否存在该凭据。如果它已在 iCloud 钥匙串或 Google 密码管理器设置中被删除，也请在依赖方的帐户设置中将它从服务器端移除。否则，服务器将不断请求丢失的凭据并持续显示错误。

错误消息：通行密钥已存在（或依赖方定义的类似错误消息）#

• 原因： 在已经拥有同一帐户凭据的设备上尝试进行新注册。许多依赖方通过在 WebAuthn 服务器上设置 excludeCredentials 来限制每台设备或每个生态系统（例如已同步的 iCloud 钥匙串或 1Password）只能拥有一个凭据。
• 解决方案： 使用现有的凭据，或从其他设备注册新凭据。或者，在依赖方的帐户设置中删除旧凭据，然后注册新凭据。

错误消息：我们找不到匹配的通行密钥（或依赖方提供的类似消息）#

• 原因： 凭据在客户端或服务器端被手动删除。即使本地私钥仍然存在，服务器上缺少匹配的公钥也会触发此错误。
• 解决方案： 从其他设备登录或使用后备身份验证方法。然后从帐户设置中创建一个全新的凭据，这将重新建立客户端和服务器端配对。

7. 二维码和跨设备登录错误#

二维码流程使用 FIDO 混合传输（也称为 CTAP 2.2 混合）。根据 FIDO CTAP 规范，两个设备通过二维码交换一次性机密，然后通过最大范围约 3 米的低功耗蓝牙进行通信。蓝牙和近距离两者缺一不可，否则流程将无声地失败。

错误消息：我看到了一个二维码#

在最新的 iOS 上，跨设备二维码表单现在写为“扫描二维码。使用兼容设备扫描此二维码以登录...”：

在 Android 上，凭据管理器会将同一流程显示为“没有可用的登录方式”，并带有显示二维码选项以及打开 Google 密码管理器的后备选项：

• 原因： 凭据绑定到特定的帐户和平台（设备或像 iCloud 钥匙串这样的云同步平台帐户）。看到二维码意味着当前设备上没有该凭据，即使用户以前在 iOS 或 Android 上注册过。另一个常见原因是服务器通过 WebAuthn 属性 AllowCredentials 限制了其接受的凭据，而可用的本地凭据不匹配。
• 解决方案： 如果原始设备有摄像头，请扫描二维码以通过混合传输登录。否则使用后备方法，先登录然后在依赖方的帐户设置中为当前设备注册一个新凭据。

错误消息：跨设备通行密钥登录需要使用蓝牙#

• 原因： 混合传输要求两台设备之间具备低功耗蓝牙。如果 PC 或手机上的蓝牙已关闭，流程会无声地失败，并显示通用的“出现错误”或“我们无法让您登录”消息。
• 解决方案： 在两台设备上都启用蓝牙，并使它们保持在彼此大约 3 米的范围内，然后重试二维码流程。如果无法打开蓝牙（例如，受企业策略限制或旧硬件），请使用后备登录方式，然后注册设备本地凭据，这样以后的登录就不会再依赖混合传输。

8. Windows 专属错误#

在过去 18 个月里，Windows 版本发布了几个与通行密钥相关的回退问题。根据 Microsoft Windows 通行密钥文档，build 22631（2024 年 11 月）添加了原生通行密钥 UI，而 Windows 11 25H2（2025 年 11 月）添加了第三方通行密钥管理器支持。这两项改变重置了一些 Windows Hello 状态。

错误消息：请将安全密钥插入 USB 端口#

• 原因： 由于设备没有 TPM 或已禁用 Windows Hello，因此需要硬件安全密钥（例如 YubiKey）。如果在没有蓝牙的机器上（无法使用混合传输）且没有本地凭据，也会出现同样的提示。
• 解决方案： 将安全密钥（例如 YubiKey）插入 USB 端口。要跳过硬件密钥，请先启用 Windows Hello，并在下次登录前创建 Windows Hello 凭据。

错误消息：在最近的 Windows 更新后，Microsoft 帐户通行密钥持续失败#

• 原因： 有几个 Windows 11 内部预览版和发布版本破坏了 Microsoft 帐户登录流程，表现为“出现错误”、“我们无法让您登录”或在创建时无声地失败。根本原因通常是 Windows Hello 状态损坏，或是 Microsoft 帐户最初配置的设置较老。
• 解决方案： 使用密码和 MFA 登录，在 Microsoft 帐户安全设置中移除损坏的凭据并创建一个新的凭据。如果是本地帐户，请备份并清除 Windows Hello 的 NGC 文件夹（C:\Windows\ServiceProfiles\LocalService\AppData\Local\Microsoft\Ngc），然后重新注册 Windows Hello。建议将 Windows 上的 Microsoft 帐户通行密钥登录作为尽量尝试的方法（best-effort），并始终保持至少一个非通行密钥 MFA 选项处于激活状态。

9. Android 专属错误#

根据 Android 凭据管理器文档，Android 凭据管理器 API 需要 Google Play 服务 23.40 或更高版本，并依靠安全的锁屏进行用户验证。没有屏幕锁定的设备根本无法注册或使用凭据。

错误消息：未提供通行密钥 (Passkeys not offered)#

• 原因： Android 设备尚未激活屏幕锁定。Android 需要密码、图案、密码或生物识别锁定来管控对凭据的访问，因此如果没有锁定，该选项将被隐藏。
• 解决方案： 在设备的“设置 > 安全”下启用屏幕锁定，然后重试。在较旧的 Android 版本上，还需确认 Google Play 服务已更新到最新版本。

10. 通用 WebAuthn 和浏览器错误#

这些错误直接来自浏览器或 WebAuthn 层。它们被有意设计为通用的，以保护用户隐私。根据 W3C 规范，浏览器在仪式期间暴露的 DOM 异常在 10 到 14 种之间，其中最常见的（NotAllowedError）涵盖了取消、超时和系统拒绝，把它们归在一个通用的错误类别下。

错误消息：无法创建您的通行密钥 / 创建通行密钥时出错 / 生成通行密钥时出错#

• 原因： 依赖方应用出现故障、临时服务器问题或不兼容的设备设置（例如不支持 WebAuthn 的旧版操作系统）。
• 解决方案： 重新启动应用或设备并重试。如果问题仍然存在，请更新操作系统和浏览器。如果只有一个依赖方受到影响，则表明问题在服务器端，通常等待几分钟后重试即可解决。

错误消息：此设备或浏览器无法提供通行密钥#

• 原因： 浏览器或操作系统不支持 WebAuthn，或者依赖方（例如 PayPal）阻止了当前的组合。常见的例子包括旧的浏览器版本、不支持 WebAuthn 的小众浏览器，或是企业管理的采用严格策略的设备。
• 解决方案： 更新浏览器和操作系统。如果设备从根本上不兼容，请切换到支持的设备（iOS 16+ 上的 Safari、Android 9+ 上的 Chrome、Windows 10+ 上的 Edge 或 Chrome）。

错误消息：出现错误。使用您的通行密钥登录时出现问题。#

• 原因： 选择了错误的凭据、设备和服务器之间的临时网络故障或浏览器的 WebAuthn 层出现故障。
• 解决方案： 确认从提示中选择了正确的凭据。稍候片刻再试。如果问题仍然存在，请检查网络并通过在帐户设置中重新注册来重置凭据。

错误消息：出现错误。请求超时。#

• 原因： 服务器响应时间过长，通常归因于网络不稳定或高负载。Chrome 中的默认 WebAuthn 超时为 60 秒，W3C 规范定义的最大超时为 600 秒。
• 解决方案： 在稳定的连接下重试。如果连接良好，则问题在服务器端，通常等待几分钟后重试即可恢复。如果依赖方的后端经常超过默认时间，依赖方可以将其超时提高至 W3C 的上限。

错误消息：NotAllowedError。操作超时或不被允许。#

• 原因： 浏览器在仪式未完成时返回的通用 WebAuthn 错误。它可能意味着用户取消、超时、来源被拦截、缺少用户手势或平台身份验证器拒绝了请求。出于隐私原因，浏览器会隐藏具体原因。
• 解决方案： 增加依赖方的 WebAuthn 超时，并确保调用是由直接的用户操作（如按钮点击）触发的。验证依赖方 ID 是否与来源匹配，用户是否拥有可用的身份验证器，并且没有浏览器扩展程序拦截调用。终端用户通常可以通过解锁设备、确认生物识别或 PIN 提示并重试来修复。

11. 结论#

通行密钥用公钥加密取代了共享机密，从而消除了密码类别的漏洞。在实际部署中，其登录速度比密码加 OTP 的组合快了 4 到 6 倍，并且根据 Verizon的 2024 年数据泄露调查报告，68% 的数据泄露是由非恶意的人为因素（包括凭据滥用）引起的。减少这一攻击面正是其目的所在。

在实践中，上述的 15 种错误占据了我们在通行密钥社区看到的大量消费者支持工单，而正确的故障排除对于更广泛的通行密钥采用来说至关重要。遵循创建最佳实践和登录最佳实践可显着降低错误率。为了了解有关错误处理和推广细节的最新动态，请订阅 passkeys Substack，或加入 Slack 社区。

关于 Corbado

Corbado 是面向大规模运行 consumer 身份验证的 CIAM 团队的Passkey Intelligence Platform。我们让你看到 IDP 日志和通用 analytics 工具看不到的内容：哪些设备、操作系统版本、浏览器和 credential manager 支持 passkey，为什么注册没有转化为登录，WebAuthn 流程在哪里失败，以及什么时候操作系统或浏览器更新会悄悄破坏登录 — 而且无需替换 Okta、Auth0、Ping、Cognito 或你自有的 IDP。两款产品：Corbado Observe 提供 针对 passkey 及任何其他登录方式的 observability。Corbado Connect 提供 内置 analytics 的 managed passkey（与你的 IDP 并存）。VicRoads 通过 Corbado 为 500 万以上用户运行 passkey（passkey 激活率 +80%）。 与 Passkey 专家交谈 →

常见问题解答#

为什么系统要求我插入安全密钥而不是使用通行密钥？#

当禁用 Windows Hello 或没有可用的 TPM 时，会出现此提示，导致系统回退到硬件安全密钥身份验证。在设备的登录设置中启用 Windows Hello 即可解决此问题，但您必须先创建一个 Windows Hello 通行密钥才能使用它进行登录。

如何修复“无法创建您的通行密钥”错误？#

该错误通常由应用程序故障、临时服务器问题或不兼容的设备设置引起。重新启动应用程序或设备，并检查操作系统和应用程序更新通常可以解决该问题。如果问题似乎出在服务器端，建议稍后等待并重试。

为什么通行密钥身份验证总是超时？#

当服务器响应时间过长时会发生超时错误，这通常归因于网络不稳定或服务器负载过高。验证您的互联网连接是第一步。如果连接稳定，则问题很可能在服务器端，稍等片刻后重试即可解决。

如果我在设备上删除了通行密钥，但未在帐户设置中删除，会发生什么情况？#

在客户端（例如从 iCloud 钥匙串或 Google 密码管理器）删除通行密钥，而不在依赖方的帐户设置中一并移除，会导致“找不到匹配的通行密钥”错误。服务器仍然持有公钥并需要该凭据，因此在注册新的通行密钥之前，必须在客户端和服务器端同时将其删除。

使用通行密钥时出现 NotAllowedError 是什么意思？#

NotAllowedError 是通行密钥仪式未完成时浏览器返回的通用 WebAuthn 错误。它可能意味着用户取消、超时、缺少用户手势、来源被拦截或平台身份验证器拒绝了请求。出于隐私原因，浏览器会隐藏确切原因。在用户直接操作后重试流程并确认生物识别或 PIN 通常可以解决此问题。

为什么 iOS 会显示“在密码中未存储匹配的通行密钥”？#

在 iOS 18 及更高版本上，存储位置移至新的“密码”应用中，因此表述从“iCloud 钥匙串”更改为“密码”。该错误表示此设备上缺少该凭据，或者 iCloud 同步未激活。请确认在同一个 Apple ID 使用的所有 Apple 设备上都启用了 iCloud 钥匙串，通过关闭再开启 iCloud 钥匙串来强制同步，然后重试登录。如果完全没有凭据，请从依赖方的帐户设置中注册一个新的。

为什么 Android 会显示“依赖方没有可用的登录方式”？#

当当前设备上没有为请求的依赖方存储匹配的凭据时，Android 凭据管理器会显示此提示。它通常会提供一个“显示二维码”选项，以便通过 FIDO 混合传输使用来自其他设备的通行密钥，外加一个打开 Google 密码管理器的后备选项。要么用已经存有该凭据的手机扫描二维码，要么使用后备方法登录，或者在当前设备上从依赖方的帐户设置中注册一个新凭据。

跨设备通行密钥二维码流程是如何工作的？#

跨设备流程是在 CTAP 2.2 中定义的 FIDO 混合传输。桌面浏览器会显示一个包含一次性机密的二维码。手机使用摄像头扫描该二维码，并通过最大范围约 3 米的低功耗蓝牙（Bluetooth Low Energy）建立连接。用户在手机上验证后，WebAuthn 仪式将在桌面上完成。蓝牙和近距离两者缺一不可，否则流程会在出现通用的“出现错误”或“我们无法让您登录”消息后无声地失败。