Feathers客户端无法接收服务端WebSocket事件（含created事件）

1. 后端核心配置校验 #

• 检查服务层的事件声明配置：Feathers 不会默认向外广播任何服务事件，必须在服务初始化时显式在配置项中声明允许对外推送的事件列表，例如需要广播created事件，需在服务定义中加入events: ['created', 'updated', 'removed']配置，未声明的事件哪怕后端触发了服务方法，也不会通过 socket 通道推送到客户端
• 排查钩子链的拦截逻辑：检查服务对应事件的钩子链中是否存在权限校验、参数过滤逻辑中断了事件推送，特别是disallow类钩子、自定义的context.dispatch返回值异常的情况；注意只有通过服务层标准方法调用触发的实体变更，才会自动关联触发对应事件，直接操作数据库产生的实体数据变更，不会触发 Feathers 的内置事件流程
• 验证 socket 服务的挂载配置：确认后端 socket.io 中间件的 CORS 白名单覆盖了前端实际运行的地址，跨域场景下要避免把 socket 连接的 origin 校验规则和普通 HTTP 接口的 CORS 规则搞混，防止连接在握手阶段就被拒绝

2. 客户端订阅逻辑校验 #

• 确认客户端实例的初始化方式：如果用的是基于 fetch/axios 的 REST 适配器初始化的 Feathers 实例，本身没有长连接通道，自然无法接收服务端的广播事件，必须使用 socket.io 适配器绑定的实例才能订阅服务事件
• 核对订阅的触发时机：检查是否在 socket 连接完全建立完成后，再发起服务事件的订阅逻辑，Feathers 的 socket 建连是异步流程，在连接 ready 之前发起的订阅请求会因为通道未建立被静默丢弃
• 对齐前后端的服务路径：确认客户端调用app.service('xxx').on(...)时填写的路径，和后端注册的服务路径完全一致，比如后端注册服务的路径是/api/orders，客户端就不能用/orders作为服务路径订阅事件，路径不匹配会直接导致事件接收失效
• 验证鉴权流程的执行顺序：确认订阅事件前已经完成了客户端的鉴权流程，Feathers 默认只有鉴权通过的连接，才会被允许接收受限服务的广播事件

3. 网络链路连通性排查 #

• 直接在浏览器控制台监听底层 socket 原始事件：通过打印 socket 实例的所有原生事件，区分是 Feathers 封装层的事件转发逻辑问题，还是底层 socket 连接本身就存在丢包、断连问题
• 检查生产环境的反向代理配置：确认 Nginx、API 网关类配置开启了 WebSocket 升级支持，正确透传Upgrade、Connection请求头，避免把 socket 长连接请求当成普通 HTTP 短连接处理，导致连接中途断开
• 排查事件数据的序列化异常：如果推送的事件数据中包含循环引用、BigInt 等 JSON 标准无法序列化的内容，socket 通道会直接丢弃整条事件报文，不会触发客户端的订阅回调

4. 高频踩坑点快速定位 #

• 不要在原生 socket 实例上直接匹配created这类简单事件名，Feathers 对服务事件做了封装，原生 socket 层的事件名格式是带服务路径前缀的组合格式，必须通过 Feathers 实例的服务方法绑定的回调才能正确接收
• 多实例部署场景下检查 socket 消息适配器配置：如果后端是多实例运行，没有给 socket.io 配置跨实例的消息同步适配器，单实例上触发的服务事件，只会推给直连该实例的客户端，直连其他实例的客户端永远无法收到对应事件
• 避免在事件订阅回调中加入长耗时同步阻塞逻辑，防止阻塞事件循环导致后续的事件接收被延迟甚至丢失

内容的提问来源于stack exchange，提问作者Mohammad Ranjbar Z