常见问题和错误报告

当你在 web push 中遇到问题时，可能很难调试问题或找到帮助。本文档概述了一些常见问题，以及如果你在 Chrome 或 Firefox 中发现 bug 时应该怎么做。

在我们深入探讨调试推送之前，你可能会遇到调试 service worker 本身的问题，例如文件未更新、注册失败或通常只是异常行为。如果你是 service worker 开发新手，我强烈建议你查看这篇关于调试 service worker 的精彩文档。

在开发和测试 web push 时，有两个不同的阶段需要检查，每个阶段都有自己的一组常见问题。

  • 发送消息： 确保消息发送成功。你应该收到 201 HTTP 代码。如果没有
  • 接收消息： 如果你能够成功发送消息，但浏览器未收到消息

如果你无法发送和接收推送消息，并且本文档中的相关部分无法帮助你调试问题，那么你可能在推送机制本身中发现了 bug。在这种情况下，请参阅“提交错误报告”部分，提交一份包含所有必要信息的良好错误报告，以加快 bug 修复过程。

在我们开始之前，我想强调一点，Firefox 和 Mozilla AutoPush Service 具有出色的错误消息。 如果你遇到困难并且不确定问题是什么，请在 Firefox 中进行测试，看看是否能获得更有帮助的错误消息。

授权问题

授权问题是开发者在开始使用 web push 时遇到的最常见问题之一。这通常是站点应用程序服务器密钥（也称为 VAPID 密钥）配置的问题。

在 Firefox 和 Chrome 中支持推送的最简单方法是在 subscribe() 调用中提供 applicationServerKey。缺点是，前端和服务器密钥之间的任何差异都将导致授权错误。

在 Chrome 和 FCM 上

对于使用 FCM 作为推送服务的 Chrome 浏览器，你将收到来自 FCM 的 UnauthorizedRegistration 响应，其中包含一系列不同的错误，所有这些错误都与应用程序服务器密钥有关。

在以下任何情况下，你都会收到 UnauthorizedRegistration 错误

  • 如果你未在发送到 FCM 的请求中定义 Authorization 标头。
  • 用于订阅用户的应用程序密钥与用于签署 Authorization 标头的密钥不匹配。
  • JWT 中的过期时间无效，即过期时间超过 24 小时或 JWT 已过期。
  • JWT 格式错误或具有无效值。

完整的错误响应如下所示

<html>
  <head>
    <title>UnauthorizedRegistration</title>
  </head>
  <body bgcolor="#FFFFFF" text="#000000">
    <h1>UnauthorizedRegistration</h1>

    <h2>Error 400</h2>
  </body>
</html>

如果你在 Chrome 中收到此错误消息，请考虑在 Firefox 中进行测试，看看是否能更深入地了解问题。

Firefox 和 Mozilla AutoPush

Firefox 和 Mozilla AutoPush 为 Authorization 问题提供了一组友好的错误消息。

如果推送请求中未包含 Authorization 标头，你还会收到来自 Mozilla AutoPush 的 Unauthorized 错误响应。

{
  "errno": 109,
  "message": "Request did not validate missing authorization header",
  "code": 401,
  "more_info": "http://autopush.readthedocs.io/en/latest/http.html#error-codes",
  "error": "Unauthorized"
}

如果 JWT 中的过期时间已过期，你还会收到 Unauthorized 错误，其中包含解释令牌已过期的消息。

{
  "code": 401,
  "errno": 109,
  "error": "Unauthorized",
  "more_info": "http://autopush.readthedocs.io/en/latest/http.html#error-codes",
  "message": "Request did not validate Invalid bearer token: Auth expired"
}

如果用户订阅时和签署 Authorization 标头时应用程序服务器密钥不同，则会返回“未找到”错误

{
  "errno": 102,
  "message": "Request did not validate invalid token",
  "code": 404,
  "more_info": "http://autopush.readthedocs.io/en/latest/http.html#error-codes",
  "error": "Not Found"
}

最后，如果你的 JWT 中有无效值（例如，如果“alg”值是意外值），你将收到来自 Mozilla AutoPush 的以下错误

{
  "code": 401,
  "errno": 109,
  "error": "Unauthorized",
  "more_info": "http://autopush.readthedocs.io/en/latest/http.html#error-codes",
  "message": "Request did not validate Invalid Authorization Header"
}

HTTP 状态代码

一系列问题可能导致推送服务返回非 201 响应代码。下面列出了 HTTP 状态代码及其与 web push 相关的含义。

状态代码 描述
429 请求过多。你的应用程序服务器已达到推送服务的速率限制。来自服务的响应应包含 'Retry-After' 标头，以指示在可以发出另一个请求之前需要等待多长时间。
400 无效请求。你的某个标头无效或格式错误。
404 未找到。在这种情况下，你应该从后端删除 PushSubscription，并等待重新订阅用户的机会。
410 已失效。订阅不再有效，应从后端删除。可以通过在 `PushSubscription` 上调用 `unsubscribe()` 来重现此情况。
413 Payload 大小过大。推送服务必须支持的最小 payload 大小为 4096 字节（或 4kb）。任何更大的 payload 都可能导致此错误。

如果 HTTP 状态代码不在列表中，并且错误消息没有帮助，请查看 Web Push Protocol 规范，查看是否引用了该状态代码以及何时可以使用该状态代码的场景。

Payload 加密问题

如果你可以成功触发推送消息（即，向 web push 服务发送消息并收到 201 响应代码），但推送事件永远不会在你的 service worker 中触发，这通常表示浏览器未能解密它收到的消息。

如果是这种情况，你应该在 Firefox 的 DevTools 控制台中看到如下错误消息

Firefox DevTools with decryption message.

要检查这是否是 Chrome 中的问题，请执行以下操作

  1. 转到 about://gcm-internals 并单击“开始记录”按钮。

Chrome GCM internals record.

  1. 触发推送消息，并在“消息解密失败日志”下查看。

GCM internals decryption log.

如果 payload 解密存在问题，你将看到类似于上面显示的错误。（请注意详细信息列中的 AES-GCM decryption failed 消息。）

如果这是你的问题，有一些工具可能有助于调试加密

连接问题

如果你在 service worker 中没有收到推送事件，并且没有看到任何解密错误，那么可能是浏览器未能连接到推送服务。

在 Chrome 中，你可以通过检查 about://gcm-internals 中的“接收消息日志”来检查浏览器是否正在接收消息。

GCM internals receive message log.

如果你没有及时看到消息到达，请确保浏览器的连接状态为 CONNECTED

GCM internals connection state.

如果它不是 'CONNECTED'，你可能需要删除当前的个人资料并创建一个新的个人资料。如果这仍然不能解决问题，请按照下面的建议提交错误报告。

提交错误报告

如果以上方法都无法帮助你解决问题，并且没有任何迹象表明问题可能是什么，请针对你遇到问题的浏览器提交问题

对于 Chrome，你可以在此处提交问题：https://bugs.chromium.org/p/chromium/issues/list 对于 Firefox，你应该在以下网址提交问题：https://bugzilla.mozilla.org/

为了提供良好的错误报告，你应该提供以下详细信息

  • 你已测试过的浏览器（例如，Chrome 版本 50、Chrome 版本 51、Firefox 版本 50、Firefox 版本 51）。
  • 一个演示问题的 PushSubscription 示例。
  • 包括任何示例请求（即，发送到推送服务的网络请求的内容，包括标头）。
  • 也包括来自网络请求的任何示例响应。

如果你可以提供可重现的示例，无论是源代码还是托管网站，通常可以加快诊断和解决问题的速度。

下一步去哪里

代码实验室