Web Push 通知中 VAPID 的 aud 字段缺失错误解决方案-Python教程-PHP中文网

使用 pywebpush 发送 Web Push 时出现 “Missing 'aud' from claims” 错误，根本原因在于手动指定 aud 后与库的自动填充逻辑冲突；正确做法是将其设为空字符串，交由库动态生成符合规范的 aud 值。

使用 `pywebpush` 发送 web push 时出现 “missing 'aud' from claims” 错误，根本原因在于手动指定 `aud` 后与库的自动填充逻辑冲突；正确做法是将其设为空字符串，交由库动态生成符合规范的 `aud` 值。

在基于 VAPID（Voluntary Application Server Identification）协议的 Web Push 实现中，aud（Audience）字段用于标识推送请求的目标服务端地址（即应用的 origin），其值必须严格匹配订阅端发起 serviceWorkerRegistration.pushManager.subscribe() 时所处的页面协议、主机名和端口（例如 https://chat.bitsquad.ru）。虽然 RFC 8292 明确要求 aud 必须存在且格式合规，但 pywebpush 库的设计逻辑是：若用户显式传入 vapid_claims['aud']，则直接校验其合法性；若未提供或设为空字符串，则由库根据 subscription_info['endpoint'] 自动推导并注入正确的 aud 值。

因此，你遇到的 ValueError: Missing 'aud' from claims 并非因为 aud 字段真的缺失，而是因为 pywebpush 在内部校验时发现你提供的 aud 值（https://chat.bitsquad.ru/）末尾多了一个斜杠 / —— 这违反了规范中对 aud 必须为 scheme + host + optional port（不含路径）的要求。https://chat.bitsquad.ru/ 中的尾部 / 会被视为非法路径成分，导致校验失败并抛出误导性错误信息。

✅ 正确做法是：将 aud 显式设为空字符串，让 pywebpush 自动解析并填充：

from pywebpush import webpush, WebPushException

vapid_private_key_pem = "KE0RL_B2SY1AVcpHRWgTzC68or6cLC4RZaHmkM4ZsLk"

def send_push_notification(subscription_info, data):
    vapid_claims = {
        "sub": "mailto:admin@bitsquad.ru",  # 推荐使用真实联系邮箱
        "aud": ""  # ⚠️ 关键：留空，由 pywebpush 自动填充
    }

    try:
        response = webpush(
            subscription_info=subscription_info,
            data=data,
            vapid_private_key=vapid_private_key_pem,
            vapid_claims=vapid_claims
        )
        print("Push sent successfully:", response.status_code)
        return True
    except WebPushException as ex:
        print("Web push failure:", str(ex))
        return False

? 注意事项与最佳实践：

✅ aud 必须为空字符串 ""（不可为 None 或省略），否则库无法触发自动填充逻辑；
✅ 确保 subscription_info['endpoint'] 是合法的 Push Service 地址（如 https://fcm.googleapis.com/fcm/send/... 或 https://updates.push.services.mozilla.com/wpush/...），pywebpush 会从中提取 origin 作为 aud；
✅ sub 字段应为 mailto: 开头的有效邮箱地址，用于在推送服务方标识应用所有者；
❌ 不要手动拼接 aud（如 https://domain.com），尤其注意移除路径、查询参数和尾部斜杠；
? 私钥格式需为 PEM 编码的 EC P-256 私钥（Base64 编码后无换行），建议使用 py_vapid.generate_keys() 生成并持久化密钥对，而非硬编码；
? 开发时可启用 pywebpush 的调试日志：import logging; logging.basicConfig(level=logging.DEBUG)，观察 aud 实际注入值。

综上，该错误本质是库与规范之间的职责划分问题：VAPID 的 aud 应由客户端运行环境（即推送服务 endpoint）决定，而非由开发者静态指定。遵循“空 aud → 自动推导”这一约定，即可彻底规避该异常，并确保跨浏览器（Chrome/Firefox/Edge）推送的兼容性与可靠性。