生产环境 WebAuthn 错误终极指南（2026）

在生产环境中，WebAuthn 错误令人困惑，因为浏览器暴露的一小部分 DOMException 名称（如 NotAllowedError）可能代表多种根本原因。此外，绝大多数“错误”——在经过优化的大规模部署中通常超过 95%——实际上是预期行为（用户中止了操作系统的通行密钥提示）。

在 Passkeys Debugger 中体验 passkey 流程。

免费试用

如果您想了解这些名称的规范定义，请从 MDN DOMException 开始。有关导致这些异常的 WebAuthn 特定条件（以及浏览器需要执行的内容），请参阅 W3C Web Authentication 规范。

如果您将所有错误都视为“错误（bugs）”，您将会采取错误的行动：

• 您会用正常的取消操作污染您的错误指标
• 您会错过隐藏在大量 NotAllowedError 中的真正回归
• 您会发布让用户感到困惑的 UI，而不是帮助他们恢复

在本文中，我们解答：

• 最常见的 WebAuthn 错误名称在真实流量中通常意味着什么？
• 如何将 NotAllowedError 消除歧义并划分为可操作的类别（取消 vs 超时 vs 可用性）？
• 为什么相同的错误根据操作（条件 UI 登录 vs 模态登录 vs 通行密钥创建 vs 条件创建）意味着不同的事情？
• 您应该捕获什么最低限度的上下文，以便“失败了”成为一个可重现的问题？

如果您只需要快速映射以解除调试阻塞，请从下表开始。它偏向于团队在仪表板和支持工单中实际看到的内容。

很容易错过的一点是：相同的 error.name 可能根据操作类型意味着非常不同的事情。在阅读以下部分时，请牢记操作上下文。在实践中，通行密钥创建（注册）错误通常远远超过登录错误——上表适用于两者，但创建是大部分数量集中的地方。

接下来，我们将更深入地探讨 NotAllowedError，因为这是您会看到最多、也是团队最常误解的一个。

NotAllowedError 往往看起来像“通行密钥失败”，但通常是平台告诉您用户没有完成 OS UI。关键是将其拆分为您可以采取行动的类别。

您将在浏览器控制台中看到的内容：

所有这些都会表现为 error.name === "NotAllowedError"。error.message 因浏览器引擎和潜在原因而异，但结果是一样的：仪式没有完成。

这适用于登录和通行密钥创建。在登录期间（条件 UI、带有或不带有 allowList 的模态），NotAllowedError 通常意味着用户没有完成仪式。在通行密钥创建期间，相同的错误由于不同的原因浮现：用户解散了创建对话框（条件创建未起作用），或者页面在自动触发的附加过程中失去了焦点。操作类型改变了错误的含义以及您应该如何处理它。

时间往往是一个被低估的信号。 点击后不到一秒钟的错误通常是立即拒绝（环境无法做到、文档未获得焦点、缺少功能）。几秒钟后的错误是用户取消（他们看到了对话框并决定不继续）。30 秒以上的错误是超时。在原生平台上，时间尤为重要：身份验证器往返、生物识别提示和凭证管理器交接都有特征持续时间，可帮助您区分“不工作”和“用户走开了”。您仍然无法轻松区分是否存在通行密钥。

您不需要完美的信号。您需要足够的上下文来避免以相同方式处理每个 NotAllowedError。iOS/Safari 在下面得到了特别关注，因为它具有独特的约束（早期版本中的用户激活要求），但在原始错误量方面，Windows 和 Chromium 浏览器通常会生成比任何其他平台更多的 NotAllowedError。这些信号通常能帮您解决 80% 的问题：

这也是为什么 NotAllowedError 很少应该对用户可见的原因。这不是用户可以采取行动的消息。

上下文分类也是成功率出现最明显分歧的地方。Corbado Passkey Benchmark 2026 通行密钥身份验证成功率分析测量了大型 B2C 部署中，2026 年第一季度针对未知设备标识符优先流程的完成率为 55–95%，而已知设备返回的完成率为 95–99%。 iOS Web 标识符优先的完成率为 85–95%（% CDA 为 0–5%），Android Web 为 70–85%（% CDA 为 5–10%），macOS Web 为 70–85%（% CDA 为 10–15%），而 Windows Web 的标识符优先完成率仅为 45–60%，在 Windows 11 上 % CDA 为 55–65%，在 Windows 10 上为 40–55%。在不区分已知与未知设备上下文的情况下读取 NotAllowedError 数量，会将两种根本不同的成功机制混为一谈。

在生产环境中有一点很容易被忽略：有些用户代理可能会将超时显示为 TimeoutError，但许多团队仍然会在仪表板中看到超时被归入 NotAllowedError。无论哪种方式，都要将超时视为“仪式未完成”，并结合时间与上下文进行归类。

当操作系统工作表被关闭或超时时，您的 UI 应立即恢复并优雅地做出反应。一套实用的规则：

• 恢复登录 UI（不要让加载项一直运行）
• 保留标识符状态（不要强迫重新输入）
• 在同一屏幕上显示可见的后备方案
• 避免为预期结果显示可怕的横幅

除了基础知识：

• 将第一次中止视为正常，并提供重试和冷静解释。只有在第二次中止后，您才应建议使用后备选项。
• 允许在冷却前出现最多三次创建提示，以便惊讶的用户有第二次机会。
• 将创建和登录之间的错误计数分开，以便您进行同类比较。
• 按操作系统、浏览器和设备细分错误率，以便您发现摩擦实际存在的地方。

如果您的“取消”真正很高，下一步是修复它们背后的根本原因：提示时间、QR 惊讶和低可用性。

从快速移动指标的更改开始：

• 修复提示时间和用户激活（特别是在 iOS/Safari 上）。
• 减少 QR/混合惊讶。
• 限制提议，以便通行密钥仅在可能成功时显示。
• 使用避免在没有本地凭证存在时提示的模式。
• 处理网络不稳定： 验证期间的网络错误通常表现为通用的客户端失败。为您的遥测日志实施脱机队列，以便在用户在仪式期间断开连接时不会丢失错误数据。
• 使用检测 API 限制仪式 以免环境失败膨胀您的 NotAllowedError 类别。从 isUVPAA() 作为最基本的限制开始，然后使用 getClientCapabilities() 进行更精细的检查（条件创建、条件获取、混合传输、平台身份验证器）。请注意，检测 API 可能会随着操作系统更新而崩溃：iOS 26.2 发布了一个 WebKit 错误，导致 isUVPAA() 在所有基于 WKWebView 的浏览器上返回 false，即使通行密钥工作正常，也会导致 10-25% 的 iOS 用户出现突发的 NotAllowedError 峰值。

错误名称是一个不断移动的目标。有正在进行的提案为 WebAuthn 错误添加更细粒度的分类（例如，将“没有可用凭证”与“用户取消”分开）。截至 2026 年 2 月，这还没有在任何浏览器中实现，因此仍然值得根据上下文和时间构建自己的原因分类。如果您想跟踪这项工作，请参阅 WebAuthn issue #2062 和 "New Error Codes" explainer。

其余的错误名称频率较低，但在它们出现时仍然值得理解。

与 NotAllowedError 相比，AbortError 的数量不多，但当它出现时，它具有很高的诊断意义：它通常意味着仪式未完成，因为您的应用程序使请求失效——发生了导航、状态改变，或开始了第二个请求。

您将在浏览器控制台中看到的内容：

常见的生产原因包括：

• 多个并发的 WebAuthn 调用（两个提示竞争）
• 仪式进行期间的路由改变/重新渲染
• 在重试或状态清理期间调用 AbortController.abort()

要修复它，请专注于使仪式成为一个“关键部分”：

• 任何时候只允许一个正在进行的请求
• 在仪式期间阻止导航（或者干净地取消并恢复 UI）
• 将中止视为正常的控制流：显示重试按钮和后备方法

如果您看到 AbortError 集中在嵌入的界面或多域应用程序中，接下来要检查的类别是 SecurityError。

SecurityError 是浏览器在告诉您：“这个上下文不允许执行您所请求的操作。”在实践中，这几乎总是配置问题，而不是用户行为。在成熟的生产部署中，SecurityError 很少见，因为这些问题通常在集成测试期间就会被发现。如果它出现在生产环境中，通常意味着在没有正确进行 WebAuthn 配置的情况下，添加了新域名、嵌入上下文或部署目标。

常见原因包括：

• RP ID / 来源不匹配（多域设置）
• 跨域嵌入限制（iframe）
• 不安全的上下文（非 HTTPS）或被阻止的权限/策略
• .well-known/webauthn 或 .well-known/assetlinks.json 配置错误、丢失或暂时不可用。如果浏览器获取这些文件时的关键窗口内发生网络问题，将导致失败。一个常见的盲点：如果您的主页因维护而下线，well-known 文件也会离线，这会破坏依赖它们的所有依赖方的通行密钥仪式。

您将在浏览器控制台中看到的内容：

在生产环境中，SecurityError 很少见——这些问题几乎总是在集成测试中被捕获。当它们确实出现时，TLS 证书错误是最常见的遗留问题。

最快的调试循环是：

• 记录您使用的 origin 和 RP ID 输入
• 在相同的上下文中重现（顶层 vs iframe，生产域 vs 暂存）
• 如果您嵌入登录，请确认配置了 permissions policy（例如 publickey-credentials-create / publickey-credentials-get）：MDN Permissions-Policy
• 验证您的域策略
• 如果使用 iframes，请验证 feature policies

一旦 SecurityError 被处理，下一个需要认真对待的类别是一组通常表明实现错误的错误：InvalidStateError、ConstraintError 和 DataError。

Passkeys 速查表. 面向 passkey 项目的实用指南、推广模式和 KPI。

获取速查表

在成熟的通行密钥实现中，这些错误应该很少见。当它们出现时，通常表明对某个片段的选项生成是错误的，或者流程处于错误状态。

您将在浏览器控制台中看到的内容：

典型含义：

• 注册：您试图创建一个已经存在的凭证（重复）
• 登录：不太常见；通常意味着流程/状态对于平台来说是不一致的

实际处理：

• 如果它发生在手动注册中，请将其视为“已注册”并相应地路由
• 确保 excludeCredentials 列出了该用户所有现有的 credential IDs，以便身份验证器能够检测到重复项
• 在条件创建期间，InvalidStateError 是预期的，应被忽略：它意味着提供商中已存在通行密钥。NotAllowedError 和 AbortError 在条件创建期间也是如此（请参阅 conditional create on Chrome）

典型含义：身份验证器无法满足您请求的约束。

常见触发器：

• 缺少设备屏幕锁定（尤其是 Android）：平台需要生物识别或 PIN 验证，但设备未配置锁定屏幕
• 过于严格的 authenticatorAttachment 或 resident key 假设
• 在不可用的片段中实施硬性 userVerification 要求

修复：放宽限制（在可接受的情况下）或提供替代路径。对于缺少屏幕锁定的情况，请考虑检测此情况并引导用户，而不是默默失败（Android）。

典型含义：输入格式错误或不一致。

常见触发器：

• 编码错误（base64 与 base64url）
• 无效的 credential id / 质询格式

修复：在生成 WebAuthn 选项的边界处验证并规范化输入。实际上，DataError 在成熟的生产系统中实际上是不存在的——如果您的选项生成经过测试，您在仪表板中就不会看到这个问题。

如果这些错误得到控制，下一个问题是覆盖率：由于环境无法按照您的预期执行 WebAuthn 而导致用户失败？

NotSupportedError 是一个覆盖率信号，而不是可靠性信号。它通常意味着某个片段无法执行您的请求（操作系统/浏览器太旧、缺少功能、功能未启用）。

您将在浏览器控制台中看到的内容：

前两个是真正的 NotSupportedError DOMException。TypeError 条目在技术上是不同的异常类型，但代表了同类问题：浏览器或环境不支持您请求的操作。在实践中，JSON 序列化 TypeError 家族比 NotSupportedError DOMException 本身常见得多（见下文）。

常见原因包括：

• 不支持基本 WebAuthn 的较旧浏览器/操作系统版本
• 请求该平台上不可用的 WebAuthn 功能
• 尝试在不支持的设备上进行特定于平台的流程

JSON 序列化系列是生产中 NotSupportedError 级失败的最大来源。 技术上，这些表面表现为 TypeError（缺少方法），而不是 DOMException，但这正是您会遇到它们的地方。两个截然不同的根本原因：

1. 浏览器不支持 WebAuthn JSON 序列化方法。 浏览器拥有 navigator.credentials 但没有 PublicKeyCredential.parseCreationOptionsFromJSON / parseRequestOptionsFromJSON。这占该错误系列的约 90%，集中在较旧的 Safari 和 Chrome 版本中。如果您的客户端库依赖这些方法而没有后备方案，则会产生大量的错误量。
2. 密码管理器扩展破坏了 .toJSON()。 Bitwarden、LastPass 或 1Password 等扩展可以拦截仪式并返回一个看起来像凭证的对象，但它不是真正的 PublicKeyCredential 实例。在它上面调用 .toJSON() 要么抛出异常，要么返回未定义，或者对象完全是 null。这大约占该系列的 10%，但因为错误消息因浏览器而异，因此特别难以调试（Safari：“Can only call on instances of PublicKeyCredential”；Firefox：“does not implement interface PublicKeyCredential”）。

处理应该是直接而快速的：

• 立即回退到备用密码/OTP
• 记录片段以便量化覆盖缺口
• 避免在会持续失败的片段上显示通行密钥 CTA

如果覆盖率看起来不错，但在特定细分市场中仍发生失败，您可能会遇到表现为 UnknownError 的平台层问题。

UnknownError 是一个统称，用于处理那些无法清晰归入其他类别的身份验证器/操作系统失败。它通常是暂时的，但也可能在操作系统更新后激增。

您将在浏览器控制台中看到的内容：

实际处理：

• 使用重试友好的 UX（不要“责怪用户”）
• 尽可能捕获 OS/内部版本号和凭证管理器/提供程序上下文
• 注意操作系统更新后的片段特定激增

不完全属于任何 DOMException 类别的另一个小众错误来源是：密码管理器浏览器扩展（如 Bitwarden、LastPass、1Password 等）可以拦截 WebAuthn API 调用并返回非标准响应。虽然与用户取消相比数量较小，但它们值得跟踪，因为它们始终如一地影响特定的用户群体并且症状令人困惑：返回的凭证对象上缺少方法、意外的错误类型，或者是与任何文档中描述的 WebAuthn 错误都不匹配的格式错误响应。这些错误通常表现为 UnknownError 或未分类异常。如果发现某个特定浏览器上错误激增，且没有操作系统级别的解释，请检查是否涉及了凭证管理器扩展。

到目前为止，我们已经介绍了 Web 浏览器的错误名称。但是，如果您还发布原生应用，情况会有所不同——在某些方面甚至会更好。

上面的内容涵盖了 Web 浏览器。原生应用——带有 ASAuthorization 框架的 iOS，带有 Credential Manager 的 Android——共享相同的基本错误类别，但在重要方面有所不同：

1. “无凭证”是一个明确的信号。 在网页端，出于隐私原因，浏览器将“无可用凭证”和“用户取消”合并到同一个 NotAllowedError 中。在原生应用中，如果在 iOS (ASAuthorizationController) 上使用 preferImmediatelyAvailableCredentials，或者在 Android (GetCredentialRequest) 上使用 setPreferImmediatelyAvailableCredentials(true)，系统会指示操作系统只展示设备上已有的凭证，如果没有，则立即失败。这就为您提供了一个浏览器无法提供的干净的“无凭证”返回结果。

2. 凭证提供程序的处于可见状态。 原生平台在某些情况下可以告诉您未安装、未配置或未将凭证提供程序（如 Google Password Manager、iCloud Keychain、1Password 等）设置为默认值并对此作出反应。在 Web 上，此信息隐藏在不透明的 NotAllowedError 消息后面。

3. 错误消息更加具体。 由于用户已安装该应用，从而与依赖方建立了信任关系，因此操作系统将提供更多诊断详细信息。适用于 Web 浏览器以保持模糊的隐私考量在应用已经存在于设备上的情况下并不以相同的方式适用。iOS 以用户设备语言返回本地化消息。Android 会返回带有原因链的结构化错误类型。这使调试更容易，但也意味着您的错误处理必须考虑到本地化和特定于平台的错误格式。

iOS 通过 ASAuthorization 框架公开通行密钥错误。所有错误都在 authorizationController(controller:didCompleteWithError:) 委托回调中以 NSError 对象的形式到达。

按域 + 代码进行分类，而不是按消息字符串。 主要的错误域是 com.apple.AuthenticationServices.AuthorizationError（ASAuthorizationError.errorDomain）。通过 let nsError = error as NSError 转换错误并匹配 .domain 和 .code。在生产环境中切勿对 .localizedDescription 进行匹配——Apple 的消息已本地化为 30 多种语言，并可能随着 OS 版本的升级而改变。下面列出的消息字符串对于在日志中识别错误很有用，但它们不能用作分类标准。

公共 ASAuthorizationError 代码：

生产环境中最重要的区别：自 iOS 18 起，重复凭证返回其自己的错误代码 1006 (MatchedExcludedCredential)。 在 iOS 17 及更早版本中，重复凭证隐藏在代码 1004 (Failed) 内部。在 iOS 18+ 上，区别是结构性的（不同的错误代码），而不是文本上的。

常见运行时错误（日志级参考）：

这些消息会出现在特定失败场景的 localizedDescription 或 userInfo 中。请使用它们进行日志搜索和调试，而不要用作程序化的分类。

本地化的“无凭证”消息（代码 1005）：

当设置了 preferImmediatelyAvailableCredentials 且不存在通行密钥时，iOS 会返回代码 1005 (NotInteractive)，并附带一条采用用户设备语言的本地化消息。这是原生应用程序独有的 - Web 浏览器从不公开此信号。该消息始终以 The operation couldn't be completed. 开头，后跟本地化文本：

英语语言环境设备通常会在 API 层面解决“没有凭证”的问题，然后 ASAuthorization 框架才会返回本地化的错误，这就是为什么上面没有显示英语变体的原因。在编程时，始终匹配代码 1005，而不是解析这些字符串。

Android 通过凭证管理器 API (androidx.credentials) 公开通行密钥错误。错误消息包括主要消息，通常还包括具有其他详细信息的 cause。与 iOS 相比，Android 提供了结构化程度更高的错误类型以及更明确的配置问题原因。

用户取消和凭证检测：

配置和安全错误：

平台和身份验证器错误：

下图显示了上面讨论的所有层 - 基础架构、环境、操作类型、分类和检测 - 是如何端到端连接的。这是您在设计错误跟踪时应具备的心智模型。

flowchart TD
    %% Global Styles
    classDef expected fill:#e3f2fd,stroke:#1565c0,stroke-width:2px;
    classDef unexpected fill:#ffebee,stroke:#c62828,stroke-width:2px;
    classDef network fill:#fff3e0,stroke:#ef6c00,stroke-dasharray: 5 5;
    classDef env fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px;
    classDef action fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px;

    %% --- LEFT SIDE: NETWORK & SERVER ---
    subgraph Infrastructure ["基础结构 (服务器/网络)"]
        direction TB
        ServerErr["服务器端错误<br/>500 / 逻辑错误"]:::network
        NetErr["网络错误<br/>超时 / 400 Bad Request"]:::network

        ServerErr & NetErr -->|表现为| ClientManifest["客户端通用错误"]
    end

    %% --- CENTER: THE ENVIRONMENT STACK (From Sketch) ---
    subgraph Environment ["环境 (客户端)"]
        direction TB

        %% Layer 1: Platform Type
        subgraph Type ["第 1 层：平台"]
            Web["Web / 浏览器"]
            Native["原生 / App"]
        end

        %% Layer 2: OS Context
        subgraph OS_Layer ["第 2 层：操作系统及版本"]
            OS_Web["操作系统：Windows、macOS、Linux"]
            OS_Nat["操作系统：iOS、Android"]
            OS_Ver["操作系统版本 / 设置<br/>（屏幕锁、生物识别）"]

            Web --> OS_Web
            Native --> OS_Nat
            OS_Web & OS_Nat --> OS_Ver
        end

        %% Layer 3: Client Software
        subgraph Client_Layer ["第 3 层：客户端软件"]
            Browser["浏览器：Chrome、Safari、Edge<br/>+ 版本"]
            App["原生应用 / WebView<br/>+ 应用版本"]

            OS_Ver --> Browser
            OS_Ver --> App
        end

        %% Layer 4: WebAuthn Operation
        subgraph Op_Layer ["第 4 层：WebAuthn 操作"]
            OpType{"操作类型"}

            Login["登录<br/>(navigator.credentials.get)"]
            Reg["注册<br/>(navigator.credentials.create)"]

            Browser & App --> OpType
            OpType --> Login
            OpType --> Reg
        end

        %% Layer 5: Sub-types & Complexity
        subgraph Modality ["第 5 层：模式与复杂性"]
            Sub_CUI["CUI / 条件 UI"]
            Sub_Auto["自动操作"]
            Sub_CDA["CDA / 跨设备身份验证"]

            Login & Reg --> Sub_CUI
            Login & Reg --> Sub_Auto
            Login & Reg --> Sub_CDA
        end
    end

    %% --- BOTTOM: CLASSIFICATION & ACTION (The "What here?" section) ---
    subgraph Analysis ["错误分析与运行时"]
        direction TB

        %% Classification
        Classification{"分类"}

        Exp["预期错误<br/>(用户中止了过程)"]:::expected
        Unexp["意外错误<br/>(系统/崩溃/未知)"]:::unexpected

        ClientManifest --> Classification
        Sub_CUI & Sub_Auto & Sub_CDA --> Classification

        Classification --> Exp
        Classification --> Unexp

        %% Detection Logic
        subgraph Detection ["检测目标"]
            P1["P1：登录问题"]
            P2["P2：创建问题"]
            Baseline["检测基线漂移<br/>(预期错误增加)"]
            NewErr["检测新异常<br/>(意外错误增加)"]
        end

        Exp --> Baseline
        Unexp --> NewErr
        Exp & Unexp --> P1 & P2

        %% Actionable Outcomes
        subgraph Action ["缓解措施"]
            Fix["部署修补程序 / 新版本"]:::action
            Fallback["激活自动后备方案<br/>(禁用通行密钥)"]:::action
        end

        P1 & P2 & NewErr --> Fix
        P1 & P2 & NewErr --> Fallback
    end

    %% Connectors
    Infrastructure -.-> Environment

关键洞察：只有在您知道环境中的哪一层产生了它、正在运行哪项操作以及错误是预期的还是非预期的之后，原始的 error.name 才具有实际意义。以下部分将介绍需要记录什么以及如何对其采取操作。

本文中大多数错误分类都可以仅使用客户端信号来完成。仅前端可观测性 SDK 可以捕获足够的上下文以对绝大多数 WebAuthn 错误进行分类。这也是 Corbado 的可观测性 SDK 的架构方式：客户端层处理错误归因、时间、操作上下文和平台检测。服务器端日志记录添加了第二层以处理只有后端才能看到的失败。

关键要求是：每次尝试必须在端到端都能够进行连接。共享的关联 ID（例如 auth_flow_id）将客户端上下文与服务器验证结果连接起来。

服务器验证失败发生在浏览器返回凭据和签名质询之后。这些应该是具有明确代码的结构化错误，而不是混入客户端 DOMException 名称的同一个桶中。参见：WebAuthn 服务器实现。

如果您想要了解完整的漏斗模型（每个步骤的流失率以及步骤之间的转化率），请参阅：使用通行密钥遥测数据以了解流失率。

订阅我们的 Passkeys Substack，获取最新消息。

订阅

有了这些数据后，结论就变得简单了：大多数“错误”将归结为 UX 修复、覆盖率修复或配置修复。但是，自己构建并维护这种分类是一项艰巨的持续工作。

上述记录清单捕获了原始信号。在大规模生产中，仅仅使用 error.name 是不够的。自行构建这种分类是一项持续不断的重要工作：错误消息会随着浏览器和操作系统的每次更新而变化，密码管理器提供程序会发布改变仪式行为的更新，每次功能发布都会出现新的错误特征。

相同的 NotAllowedError 根据浏览器未为您分离的三个维度，可能意味着六种不同的事情：

这正是 Corbado 的可观测性 SDK 旨在解决的问题。它是一个轻量级的前端集成，位于您现有的通行密钥实现之上，适用于任何 WebAuthn 服务器和任何 IDP，并在所有三个维度上自动对每一个 WebAuthn 错误进行分类：

这是 观察 层：能够洞察正在发生的情况，而无需修改您的实现。

Corbado 的管理控制台支持两条调查路径：

自上而下 (从仪表板探究根本原因)：

1. 监控两种不同的异常类型：
   • 预期的错误增加（基线偏移）： 特定环境（如 iPhone 15 上的 iOS 18.2）是否出现了“用户取消”的情况逐渐增加？这通常表明操作系统更新引入了 UX 摩擦。
   • 未预期的错误增加（峰值）： 完全新的错误或是失败次数的突然激增。这通常表明存在破坏性更改（内部 IDP 堆栈更新）或新浏览器版本出现了回退。
2. 按照影响划分优先级：
   • P1：登录问题。 如果登录成功率下降，请立即发出警报。
   • P2：创建问题。 关注发展趋势，但避免因为在创建流程中出现“用户取消”高峰而叫醒工程师。
3. 深入研究环境： 使用更细化的维度（硬件，验证设置）去找出问题究竟是全局性的，还是仅限于“装载有 Android 14 系统的三星设备”。
4. 缓解措施： 若检测到重大的错误飙升情况，请准备好一个 Kill Switch。对该特定环境手动或自动禁用通行密钥，然后降级为 OTP/密码认证，以保持登录成功率并在同时开展排查。

自下而上（错误模式到影响）：

1. 从错误分类视图开始。检查分类错误模式及其数量。
2. 随着新模式的出现，细化错误映射（例如，新的浏览器版本发布了不同的错误消息）。
3. 错误与 KPI 更改交叉关联并作为仪表板上的注释显示，因此特定错误模式的峰值会自动链接到其影响的指标。

这两条路径殊途同归：自上而下的分析能够告诉您哪里出了问题，而自下而上的排查则能告诉您原因。AI Analytics Assistant 允许您通过自然语言就错误数据和采用指标提出问题，从而将这两种分析方式连接起来。

如果团队想要对这些信号采取行动，可以转换到 采用 阶段，该阶段添加了智能通行密钥层以自动控制仪式的进行、优化注册提示，并能够修复被破坏的通行密钥状态。对于受监管的环境或超大规模的部署，企业版 则增加了单租户托管、SIEM 集成以及符合 PSD2 标准的配置支持。

获取面向企业的免费 passkey 白皮书。

免费获取

WebAuthn 错误名称并不是定论。它们只是提示——只有当您将它们与操作类型、时间以及平台上下文联系起来时，它们才会变得具有可操作性。

• 生产中最常见的 WebAuthn 错误名称意味着什么？ 大多数可以映射为一小部分的层次：用户控制流程 (NotAllowedError)，应用程序生命周期 / 并发性 (AbortError)，安全上下文 / 配置 (SecurityError)，或者是选项/状态的错误（InvalidStateError，ConstraintError，DataError）。占据数量绝大部分的是 NotAllowedError，而且其中大部分是预期的行为（用户关闭了提示框）。
• 你如何消除 NotAllowedError 的歧义？ 利用时序（立即拒绝还是用户取消，亦或是超时），是否有扫码 / 混合认证的标识（可用性不匹配的情况），用户激活的上下文（特别是在 iOS / Safari 上）以及操作类型（条件 UI 与模态框登录，或者通行密钥创建与条件创建相对比）。不要把所有的 NotAllowedError 都当做同一种失败模式来处理。
• 为什么操作类型如此重要？ 相同的 error.name 在条件 UI 登录的过程中出现，与在条件创建或者手动创建通行密钥的过程中（用户解散了对话框）相比，传递出的完全是一个不同的信号。将操作类型和错误一起记录下来，这正是将通用的 NotAllowedError 转化为可以采取措施处理的过程。
• 记录下哪些最少的上下文才能够让错误可以被调试？ 记录下 error.name，操作类型，从操作开始计算的故障响应时间，流程类型，是否展示过二维码/混合用户界面，操作系统 / 浏览器 / 设备信息（包含版本号），关联 id (auth_flow_id) 以及将服务器验证遭拒信息当成明确代码保留下来。

有两个贯穿于所有的错误类型的经验法则：永远不要向用户直接展示那些原始的浏览器错误——请始终给他们提供一条明晰的回退路径——将本地化的认证尝试与扫码 / 混合跨设备尝试区分开来，因为他们各自的故障原因是不一样的而且也需要用不同的方法来修复。 随着规模的扩大，横跨不同的浏览器、操作系统版本和凭证管理器来持续维护错误的分类是一项长期工作。与从零开始自行构建相比，可以考虑使用一种带有经过持续维护的模式库的可观测性 SDK。

关于 Corbado

Corbado 是面向大规模运行 consumer 身份验证的 CIAM 团队的Authentication 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 专家交谈 →

在网页端，出于隐私原因，浏览器将这两种情况都合并为 NotAllowedError，因此您无法直接区分它们。使用时间作为辅助手段：不到 1 秒的错误通常表示环境拒绝或功能缺失，而 1-15 秒表明用户看到了对话框并关闭了它。在原生 iOS 和 Android 应用上，在请求之前设置 preferImmediatelyAvailableCredentials 可以在显示任何 UI 之前为您提供干净的“无凭证”信号（iOS 代码 1005，Android GetCredentialRequest）。

在优化过的大规模通行密钥部署中，超过 95% 的记录的 WebAuthn 错误是预期的用户中止，而不是系统故障。在不区分“用户关闭提示”和真正故障的情况下，跟踪原始 error.name 计数会虚增错误指标，掩盖隐藏在 NotAllowedError 量内部的真正性能下降。按操作类型分离您的计数，并将用户取消分类桶与意外错误（如 SecurityError、ConstraintError 和 DataError）分开处理。

iOS 代码 1005（NotInteractive）表示在 ASAuthorizationController 上设置了 preferImmediatelyAvailableCredentials 时，设备上没有可用的通行密钥，并且没有向用户显示任何 UI。这是一个明确的“此设备上不存在通行密钥”信号，由于隐私限制，Web 浏览器无法提供此信号。始终根据数字代码进行分类，而不是 localizedDescription，因为苹果的消息已本地化为 30 多种语言，并且可能随着操作系统版本的更新而改变。

在条件创建期间，NotAllowedError、AbortError 和 InvalidStateError 都是预期结果，应该直接忽略，而不是作为错误抛出。NotAllowedError 表示自动填充不可用或页面失去焦点，而 InvalidStateError 表示提供程序中已存在通行密钥。在尝试调用之前，使用 getClientCapabilities() 验证 conditionalCreate 支持，并检查文档可见性状态，以避免错误计数虚高。

捕获操作类型（条件 UI、模态登录、手动创建、条件创建或自动追加）、从操作开始的错误时间、操作系统版本、浏览器版本、硬件型号、是否出现二维码/混合 UI 以及与服务器端日志连接的关联 ID。服务器验证失败（例如挑战不匹配、无效签名和未找到凭证）应作为明确的结构化代码记录，而不是混合到与客户端 DOMException 名称相同的桶中。这些信号在一起可以将绝大多数错误准确无误地分类为可采取行动的桶。