Cocos Creator 前端联网知识概要：微信小游戏网络栈全景

这篇是我在 Cocos Creator 上做微信小游戏联网对战的知识地图整理。目标：把"要懂哪些点、每个点的坑在哪"一次铺开，细节另开文章。

一、传输选型

• WebSocket 是微信端实时对战的常用选择：小游戏环境没有裸 TCP/UDP，实时只能走它；HTTP 轮询只适合非实时接口。原生平台则可以裸 TCP 或 UDP+KCP。
• 直接用引擎自带的 WebSocket，编辑器/浏览器/微信小游戏全端同一套 API，不需要为微信再封一层。
• 线上必须 wss:// + 已备案域名 + 进 mp 后台的 socket 合法域名白名单，开发期用 ws://127.0.0.1 + 开发者工具关掉域名校验。

二、协议与序列化

• 自定义包头 + protobuf 消息体是常见组合：包头承载路由与分拣所需的信息，消息体用 protobuf 二进制。具体字段布局属于服务端实现细节，不要写进任何公开文档。
• 工具链：proto 文件 → pbjs/pbts 生成静态 JS + d.ts；服务端 proto 由同一个工具从 C# 消息类生成，两端同源是防漂移的关键。
• 经验：消息类型注册表缺失是"包根本发不出去"这类静默失败的来源——收到对端未注册的消息要能看见日志。

三、连接管理：心跳、重连、假死

• 假死是微信端的特色坑：socket 断网/切后台后 onClose 不一定触发，必须靠"收包静默超时"主动判死（我的阈值 8s），超时主动 close 再重连。
• 重连用指数退避（1/2/4/8s 封顶），并监听微信的 onShow 与网络切换事件做即时校准。
• 静默探测要分场景：对局中服务端有帧流量可以当活性证明；大厅静默期不启探测，否则误杀。

四、帧同步客户端的职责

• 本地固定步进自治推进 + 服务端定帧广播指令：指令带未来帧号，到点才应用。
• 断线恢复三件套：重连成功后重新登录 → 重新进逻辑服（绑路由）→ 发 Resume 拉帧历史追帧——少一步消息就会被服务端静默丢弃。
• 断流期间冻结自治推进，否则错过的指令帧落在"过去帧"，双端就此分歧。

五、调试与可观测性

• 发包/收包日志要能一键开关（联调期的 [SEND]/[RECV] 打点救了无数次命）。
• 无头协议冒烟脚本（Node 直连 WebSocket 按协议发包）能在不开编辑器的情况下回归整条链路，强烈建议备一个。