webman需调用fcm http v1 api实现推送，因其无laravel式通知抽象层；须用php客户端构造json payload并动态获取刷新access_token，注意token有效性、平台字段差异及错误码排查。

Webman 本身不内置推送能力，必须通过调用 FCM HTTP v1 API 实现跨平台推送；直接依赖 firebase_messaging 或类似客户端 SDK 完全无效。

为什么 Webman 不能像 Laravel 那样用通知频道集成 FCM

Webman 是轻量级协程框架，没有 Laravel 的 Notification 抽象层和 channel 概念。所谓“集成 Firebase”，本质是后端主动发起 HTTPS 请求到 FCM 服务端，和前端 SDK 无关。

• 所有推送逻辑必须由 Webman 控制器或任务中调用 https://fcm.googleapis.com/v1/projects/{project_id}/messages:send
• firebase-admin SDK（Node.js 版）虽可简化签名，但 Webman 运行在 PHP 环境，无法直接使用
• 你真正需要的是：PHP HTTP 客户端 + 正确构造的 JSON payload + 有效的 access_token

获取并刷新 FCM access_token 的正确姿势

FCM v1 API 要求每个请求携带 OAuth2 access_token，它 1 小时过期，不能硬编码或手动复制粘贴。

Webman 2.2.0

Webman 2.2.0版本强化了 TCP/UDP 服务支持，优化路由组管理，并增强异步任务处理能力。结合协程与连接池技术，Webman 能轻松应对高并发场景，适用于网站、接口服务、即时通讯、物联网及游戏开发，兼具高性能、灵活扩展与稳定可靠，是多场景 PHP 服务开发的理想选择。

下载

• 从 Firebase 控制台 → 项目设置 → 服务账号 → 生成新的私钥 JSON 文件（如 firebase-adminsdk.json）
• 用 PHP 解析该文件，提取 client_email 和 private_key
• 调用 Google OAuth2 令牌端点 https://oauth2.googleapis.com/token，用 JWT 签发临时 token —— 必须自己实现或复用 google/auth 库
• 缓存 token 到 Redis 或内存，每次发送前检查是否剩余 600 秒（10 分钟），过期则刷新

发送请求时 payload 容易出错的三个字段

Android/iOS/Web 对字段容忍度不同，一个错配就会导致静默失败或只在部分平台生效。

• message.token：必须是设备最新 registration token，iOS 的 token 有空格和大小写敏感，Web 的 subscription.endpoint 字符串不能截断
• message.android.notification.sound：设为 "default" 才触发系统音效；设为空字符串或 null 则静音
• message.webpush.fcm_options.link：Web 推送点击跳转地址，必须是同源 URL（如 https://yourdomain.com/notify），否则浏览器拒绝展示

调试时最常卡住的错误信息

FCM 返回的 HTTP 状态码和 JSON body 很关键，别只看 200/400 就下结论。

• 401 Unauthorized：token 过期或签名错误，检查 JWT header 是否含 "alg": "RS256" 和 "typ": "JWT"
• 404 NOT_FOUND：message.token 无效，或设备已卸载应用、用户拒收 Web Push
• 400 BAD REQUEST 中出现 "registration token is not valid"：token 格式错误（iOS token 常见多一个空格）、或已被 FCM 失效（如用户重装 App）
• 403 Forbidden：服务账号权限不足，确认 Firebase 项目中该账号拥有 firebase.messaging.sender 角色

真正麻烦的不是第一次发出去，而是 token 过期轮换、厂商通道降级、Web Push 订阅失效这些隐性衰减——它们不会报错，只会让到达率缓慢下滑。建议在 Webman 里加个定时任务，每天拉取一次各平台 token 的有效性统计，比等运营反馈“怎么今天推送没声音”要主动得多。