Webpush库必须通过Composer安装并满足PHP≥7.2、openssl和mbstring扩展要求,否则因缺失GuzzleHttp/Psr7/Request或Base64Url::encode()等依赖导致实例化失败或加密报错。

Webpush 库(web-push-php)本身不依赖 Composer 自动加载机制来发送通知,但必须通过 Composer 安装并正确配置依赖链才能工作;直接 require 手动文件会缺失 guzzlehttp/psr7、minishift/base64url 等关键依赖,导致 WebPush 类实例化失败或加密报错。
安装 web-push-php 及其底层依赖
该库对 PHP 版本和扩展有硬性要求:PHP ≥ 7.2,且必须启用 openssl 和 mbstring。Composer 安装时若跳过依赖检查,后续调用 WebPush\WebPush::__construct() 会抛出 Class 'GuzzleHttp\Psr7\Request' not found 或 Call to undefined function Base64Url\Base64Url::encode()。
- 运行
composer require web-token/jwt-framework不是必须的——web-push-php自带轻量 JWT 实现,额外引入 jwt-framework 反而可能因签名算法冲突导致VAPID验证失败 - 务必使用
composer require minishift/web-push(官方维护的最新分支),而非已归档的web-push-php/web-push,后者不支持 PHP 8.1+ 的mb_ord()替代方案 - 如果项目启用了
composer/autoload.php的 PSR-4 自动加载,确认vendor/autoload.php已在入口脚本中require,否则new WebPush\WebPush(...)会提示类未找到
VAPID 密钥生成与存储方式
VAPID 公私钥对必须由服务端生成并长期复用,不能每次请求都重新生成;前端用公钥订阅,后端用私钥签名推送请求。把私钥硬编码在 PHP 文件里或写进 .env 都不安全,但直接丢进数据库也不合适——它需高频读取且不能被 Web 目录直接访问。
专业音乐创作规划。基于 mmx-cli(MiniMax AI)生成高质量音乐和歌曲,自动规划曲风、节奏、乐器编配和人声特色,将模糊需求转化为精准 Prompt。支持纯器乐和中文歌词歌曲。
- 推荐将私钥保存为
/var/www/private/vapid-private.key(Linux)或C:\vapid\private.key(Windows),权限设为600,并在 PHP 中用file_get_contents()读取,避免环境变量泄露风险 - 公钥必须 Base64URL 编码后传给前端,不能直接用
base64_encode()——要替换+为-、/为_、去掉末尾=,否则navigator.serviceWorker.register()会拒绝订阅 - 用
openssl genpkey -algorithm EC -out vapid-private.key -pkeyopt ec_paramgen_curve:prime256v1生成密钥;若用rsa:2048,推送会失败——Web Push 协议只接受 P-256 椭圆曲线
构造推送 payload 并处理 HTTP 响应状态
Web Push 不是“发完就完”,每个推送请求都会返回明确的 HTTP 状态码,比如 410 Gone 表示用户取消订阅,401 Unauthorized 是 VAPID 签名过期或公钥不匹配,429 Too Many Requests 则需退避重试。忽略这些状态会导致无效端点堆积、配额耗尽。
- 推送前必须校验订阅对象结构:
$subscription['endpoint']是 URL,$subscription['keys']['p256dh']和$subscription['keys']['auth']是 Base64URL 字符串,缺一不可 - payload 最大 4096 字节,超限会返回
413 Payload Too Large;建议先用json_encode($data, JSON_UNESCAPED_UNICODE)计算长度,再决定是否压缩或裁剪 - 调用
$webPush->sendOneNotification($subscription, $payload)后,检查返回的ResponseInterface对象:$response->getStatusCode()为201才算成功,其余都要记录日志并清理失效订阅
常见错误:Chrome 报错 “Failed to execute ‘showNotification’ on ‘ServiceWorkerRegistration’”
这不是 PHP 层的问题,而是前端 Service Worker 在收到推送后尝试调用 self.registration.showNotification() 失败。根本原因通常是:推送 payload 为空、notification options 缺少 title 字段、或 SW 文件未正确注册/缓存。
- 确保推送时至少传入
{"title": "Hello"},空对象{}会导致 Chrome 静默失败,且不抛 JS 异常 - Service Worker 文件(如
sw.js)必须放在网站根目录下,且响应头含Content-Type: application/javascript,否则 Firefox 会拒绝注册 - 开发阶段用
chrome://serviceworker-internals/查看 SW 状态,确认 “Waiting” 或 “Active”;若显示 “Redundant”,说明新版本未跳过等待直接激活,需在 SW 中加self.skipWaiting()
真正麻烦的是 VAPID 签名验证失败和订阅端点过期判断——这两处没有明确错误提示,只能靠反复比对 RFC8292 规范里的 JWT header、payload、signature 生成逻辑,以及检查推送响应的 WWW-Authenticate 头内容。

















