当您遇到 Web 推送问题时,可能很难调试问题或寻求帮助。本文档简要介绍了一些常见问题,以及您在 Chrome 或 Firefox 中发现 bug 时应采取的措施。
在我们深入了解推送调试之前,可能会遇到以下问题:调试 Service Worker 本身、文件未更新、注册失败或通常只是异常行为。如果您刚开始接触 Service Worker 开发,我强烈建议您查看关于调试 Service Worker 的精彩文档。
在开发和测试 Web 推送时,需要检查两个不同的阶段,每个阶段都有自己的一组常见问题:
- 发送消息:确保发送消息成功。
您应该会收到 201 HTTP 代码。否则:
- 检查授权错误:如果您收到授权错误消息,请参阅“授权问题”部分。
- 其他 API 错误:如果您收到非 201 状态代码响应,请参阅“HTTP 状态代码”部分,了解有关问题原因的指南。
- 接收消息:如果您能够成功发送消息,但浏览器上未收到消息,请执行以下操作:
如果您无法发送和接收推送消息,并且本文档中的相关部分不能帮助调试问题,则您可能发现了推送机制本身 bug。在这种情况下,请参阅提升 bug 报告部分,提交一份详尽的 bug 报告并提供所有必要信息,以加快 bug 修复过程。
在开始之前,我想提醒一下 Firefox 和 Mozilla AutoPush 服务收到很棒的错误消息。如果您遇到困难,不确定是什么问题,请在 Firefox 中进行测试,看看能否收到更实用的错误消息。
授权问题
授权问题是开发者在着手进行 Web 推送时遇到的最常见的问题之一。这通常会因为网站的应用服务器密钥(又称为 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"
}
如果用户订阅与签名授权标头期间的应用服务器密钥不同,系统将返回 Not Found
错误:
{
"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 推送的关系。
状态代码 | 说明 |
---|---|
429 | 请求数量过多。您的应用服务器已达到推送服务的速率限制。服务的响应应包含“重试”标头,以指示在多长时间后可以发出其他请求。 |
400 | 请求无效。您有一个标头无效或格式不正确。 |
404 | 未找到。在这种情况下,您应该从后端删除 PushSubscription,并等待机会重新订阅用户。 |
410 | 不见了。订阅不再有效,应从您的后端中移除。这可以通过对“PushSubscription”调用“unsubscribe()”来重现。 |
413 | 载荷大小过大。推送服务必须支持的最小载荷为 4096 字节(或 4kb)。大于该值就会导致此错误。 |
如果 HTTP 状态代码不在此列表中,并且错误消息没有帮助,请查看 Web 推送协议规范,查看是否引用了状态代码以及何时可以使用该状态代码。
载荷加密问题
如果您可以成功触发推送消息(即,向网络推送服务发送消息并接收 201 响应代码),但推送事件从未在 Service Worker 中触发,这通常表示浏览器无法解密收到的消息。
如果是这种情况,您应该会在 Firefox 的开发者工具控制台中看到如下错误消息:
若要检查 Chrome 中是否存在此问题,请执行以下操作:
- 前往 about://gcm-internals,然后点击“Start Recording”按钮。
- 触发推送消息,然后在“邮件解密失败日志”下查看相关信息。
如果解密载荷时出现问题,您将看到与上面显示的错误类似的错误。(请注意详细信息列中的 AES-GCM decryption failed
消息。)
如果您遇到此问题,可借助以下工具调试加密问题:
连接问题
如果您在 Service Worker 中没有收到推送事件,并且没有看到任何解密错误,则可能是因为浏览器无法连接到推送服务。
在 Chrome 中,您可以通过检查 about://gcm-internals
中的“接收消息日志”(sic) 来检查浏览器是否正在接收消息。
如果您未看到消息及时到达,请确保您的浏览器的连接状态为 CONNECTED
:
如果不是“已连接”,您可能需要删除当前配置文件,然后创建新的配置文件。如果上述操作仍无法解决问题,请按照下方建议提交 bug 报告。
引发 bug 报告
如果上述方法无法解决您的问题,并且没有迹象表明可能存在什么问题,请针对您遇到问题的浏览器提出问题:
对于 Chrome,您可前往以下网页提出问题: https://bugs.chromium.org/p/chromium/issues/list 对于 Firefox,您应前往以下网址提出问题: https://bugzilla.mozilla.org/
为了提供良好的 bug 报告,您应提供以下详细信息:
- 您测试过的浏览器(例如 Chrome 版本 50、Chrome 版本 51、Firefox 版本 50、Firefox 版本 51)。
PushSubscription
示例,可演示问题。- 包括所有示例请求(即向推送服务发出的网络请求的内容,包括标头)。
- 同时添加来自网络请求的所有示例响应。
如果您能提供可重现的示例(源代码或托管网站),通常可以加快诊断和解决问题的速度。