wx.connectSocket 是唯一连接入口但易失败，需配置合法 wss 域名、有效证书、正确时机调用；应封装全局单例，监听 onHide/onShow 实现智能重连；须自行处理粘包、心跳、异常消息及云托管特殊连接方式。
wx.connectSocket是连上的唯一入口，但直接调用它大概率失败——不是代码写错，而是环境、配置或时机没对。
必须配好 wss 域名，否则真机必断
小程序强制要求 WebSocket 使用 wss:// 协议，且域名必须提前加到「小程序管理后台 → 开发 → 开发设置 → 服务器域名」里。本地开发时开发者工具可勾选“不校验合法域名”，但真机调试或上线后，只要域名没备案或没加白名单，wx.connectSocket 就会静默失败，控制台可能只报 fail 没具体错误。
- 域名必须带
wss://前缀，不能只填example.com - 不能用 IP 地址或
localhost（真机不可达） - 若用云托管，需确认服务已开启 WebSocket 支持，并暴露正确路径（如
/ws） - 证书必须有效：自签名证书在 iOS 真机上大概率握手失败，建议用 Let’s Encrypt 或云厂商签发的证书
wx.connectSocket 调用时机很关键
很多人把 wx.connectSocket 写在 onLoad 里就完事，结果切后台再回来连接就断了，也不重连。小程序生命周期决定：页面隐藏、前后台切换、内存不足时，系统可能主动 kill 掉 socket 连接，且不会通知你。
- 不要只在页面级初始化；建议封装成全局单例（比如挂到
getApp().socket），避免多个页面重复建连 - 必须监听
onHide和onShow：切后台时缓存状态，切回前台时检查socketTask.readyState，非OPEN就主动重连 - 重连前先
wx.closeSocket()，否则新连接可能被旧 task 阻塞 - 重连要加退避策略（如 1s、2s、4s…），避免高频失败打爆服务端
消息收发必须自己处理粘包和心跳
微信小程序的 wx.onSocketMessage 每次回调只传一个 res.data，但它不保证和后端一次 send 对应——TCP 层可能拆包或合并。更麻烦的是，小程序没有内置心跳机制，WSS 连接空闲几分钟就会被中间代理（如 Nginx、微信网关）静默断开。
name wechat-article-writer-pro description 微信公众号文章完整生成技能（专业版）。输入主题即自动完成：信息调研、文章撰写（含章节配图）、5个备选爆款标题、封面图生成、带格式排版的DOCX文档输出。触发词：写公众号文章、生成公众号内容、做微信推文、公众号文章完整版。 agent_created true 微信公众号文章完整生成技能（专业版） 概述 本技能提供微信公众号文章从主题到成品的完整生成流程，在基础版之上增加：章节配图、DOCX 格式输出（含彩色重点文字和表格
- 服务端必须定期发心跳帧（如
{"type":"ping"}），小程序收到后立刻回{"type":"pong"} - 前端要自己起定时器，每 30–45 秒发一次
wx.sendSocketMessage({ data: '{"type":"ping"}' }) - 收到消息先
JSON.parse，捕获异常并丢弃非法数据，防止一次脏包导致整个消息流中断 - 如果后端返回的是二进制帧（如 ArrayBuffer），
res.data类型是ArrayBuffer，需用new TextDecoder().decode(res.data)转字符串
用 wx.cloud.connectContainer 连云托管要特别注意
如果你走微信云托管 + 容器服务，别用传统 wx.connectSocket，得用 wx.cloud.connectContainer，否则连不上。这个 API 行为和原生 socket 不完全一致，容易踩坑。
- 基础库必须 ≥
2.21.1，低版本直接报错connectContainer is not a function - 返回的
socketTask和wx.connectSocket返回对象结构相同，但底层走的是云网关通道，header参数无效，身份信息（如x-wx-openid）在 iOS 高性能+ 模式下可能丢失 -
path必须显式指定，哪怕填'/'，空字符串或不传会导致连接失败 - 云托管后端需自行解析 WebSocket Upgrade 请求，并兼容微信网关透传的协议头
真正难的从来不是连上那一瞬间，而是连上之后怎么扛住切后台、网络抖动、服务重启、消息乱序——这些细节不处理，用户一锁屏再打开，聊天就“失联”了。
