小程序socket域名

微信小程序（及其他主流小程序平台）对于 Socket 连接有着严格的 域名合法性 校验机制。开发者必须在小程序后台配置 Socket 合法域名，否则在真机预览或线上环境中将无法正常建立 WebSocket 连接。以下内容基于微信小程序官方文档及相关平台规范，涵盖核心规则、配置方法与常见问题。

一、Socket 域名要求（以微信小程序为例）

1. 小程序中使用的 WebSocket 连接 必须使用 wss:// 协议，即 安全的 WebSocket，不允许使用明文 ws:// 协议（除非在开发工具中勾选了“不校验合法域名”）。这是因为小程序强制要求所有网络请求遵循 HTTPS/WSS 安全通道，防止数据被窃听或篡改。

2. 配置的域名必须已经通过 ICP备案，且域名不能使用 IP 地址 或 localhost（开发工具本地调试除外）。同时，域名必须是开发者拥有或可合法使用的域名。

3. 每个 Socket 合法域名 只能对应一个 Socket 连接地址。如果小程序需要连接多个不同的 WebSocket 服务器，则需要在后台分别添加对应的域名。

4. 域名中不能包含 端口号，即配置时只需要填写域名（例如 wss://example.com），不能写成 wss://example.com:8080。实际连接时使用的端口默认由 WSS 协议确定为 443，如果服务端监听端口不是 443，则需要通过 反向代理（如 Nginx）将 443 端口的 WSS 流量转发到实际 WebSocket 服务端口。

5. Socket 域名 与 request 合法域名（普通 HTTP 请求）相互独立，需分别配置。一个域名无法同时覆盖两种用途，必须按照接口类型分别添加。

二、配置流程

1. 登录 微信公众平台，进入小程序管理后台。

2. 在左侧菜单选择 开发管理 -> 开发设置 -> 服务器域名。

3. 在 Socket 合法域名 一栏中，点击“修改”，输入你的 WSS 域名（如 wss://socket.example.com），保存后等待审核（通常即时生效，但部分情况下可能需要几分钟）。

4. 注意：小程序后台要求域名必须支持 HTTPS 证书，且证书链完整有效。如果证书无效，则无法通过校验。

5. 在 微信开发者工具 中，需要在“详情”->“本地设置”中勾选“不校验合法域名、web-view（业务域名）、TLS 版本以及 HTTPS 证书”才能进行本地调试；但真机预览时，必须关闭该选项，并确保后台域名配置正确。

三、技术实现中的关键点

1. 小程序端使用 wx.connectSocket() 创建连接，其中 url 参数必须是 wss:// 开头的合法域名。示例：

wx.connectSocket({ url: 'wss://socket.example.com' });

2. 开发者在本地测试时，如果服务端仅支持 ws://，可以在开发者工具中临时开启“不校验合法域名”，同时将 url 写为 ws://，但这种方法不能用于真机预览或正式发布。

3. Socket 连接 建立后，需要监听 wx.onSocketOpen、wx.onSocketMessage、wx.onSocketError、wx.onSocketClose 等事件，实现完整的数据收发与异常处理。

4. 建议在 onSocketMessage 回调中解析服务器返回的数据，并使用 wx.sendSocketMessage 发送消息。所有消息数据格式需要前后端约定（如 JSON 或二进制帧）。

5. 在 onSocketError 或 onSocketClose 事件中，需要实现 自动重连 逻辑，但重连间隔需合理（如 1 秒、2 秒、4 秒逐步退避），避免对服务器造成压力。同时，小程序进入后台时，WebSocket 连接可能被系统断开，需要在前台恢复时主动检查并重建连接。

四、注意事项与常见问题

1. 域名证书：WSS 使用的 TLS 证书必须与配置的域名匹配，且证书链完整。如果证书是自签名的，小程序端将无法信任，连接会失败。正式环境必须使用正规 CA 签发的证书。

2. 端口限制：小程序 Socket 只允许使用 443 端口。如果 WebSocket 服务运行在 8080 或其他端口，必须使用 Nginx 或云负载均衡器配置 SSL 终止 和 WebSocket 代理，将外部 443 的 WSS 流量转发到内部端口的 WS 服务。

3. 域名数量限制：微信小程序每个类型的合法域名最多可配置 20 个（不同平台可能有差异，以官方公告为准）。如果业务需要更多域名，需合并或使用域名通配符（部分平台不支持通配符）。

4. ICP 备案：域名必须已备案，且备案主体与小程序主体一致或有关联（具体规则请参考微信官方说明）。未备案的域名无法添加为合法域名。

5. 本地调试与真机差异：开发者工具中勾选了“不校验合法域名”后，可以连接任意的 ws/wss 地址；但真机预览时，即使开启了“开发调试”模式，系统仍会校验合法域名。因此，必须提前在后台配置好 Socket 域名。

6. H5 与小程序的区别：如果同时开发 H5 版本，H5 不受小程序域名限制，但小程序必须遵循上述规则。建议在架构设计时统一使用同一套 WSS 域名，便于管理。

7. Socket 连接保活：小程序端 WebSocket 有超时机制，默认 60 秒无活动可能被判定为超时。建议客户端定期发送 心跳包（如每 30 秒发送一个 ping 帧或自定义 JSON），服务端返回 pong 或对应响应，以维持连接有效。

8. 多端适配：支付宝小程序、百度小程序、字节跳动小程序等平台也有类似机制，域名要求大同小异（例如支付宝小程序要求 HTTPS/WSS，也需在小程序后台添加 socket 合法域名）。开发跨端应用时，需逐一配置。

五、推荐实践

1. 在服务端使用成熟的 WebSocket Server 库（如 Node.js 的 ws、Java 的 Netty、Go 的 gorilla/websocket），并部署在负载均衡器（如 Nginx、阿里云 SLB）后面。

2. 使用 Nginx 配置 WSS 反向代理时，需要添加以下关键指令以支持 WebSocket 升级：

proxy_set_header Upgrade $http_upgrade;

proxy_set_header Connection "upgrade";

proxy_pass http://内部服务地址;

3. 在服务端开启 TLS 1.2 及以上 版本，禁用不安全协议，并定期更新证书。

4. 对 Socket 连接 进行鉴权：建议在连接时通过 query 参数 或 子协议 携带 token，服务端校验通过后接受连接，否则拒绝。

5. 监控 Socket 连接数 和 消息错误率，及时发现异常。小程序端也应记录连接状态变化，辅助排查问题。

六、总结

小程序 Socket 域名 是平台安全策略的一部分，强制要求使用 WSS 协议、已备案域名、443 端口，并且必须在后台完成合法域名配置。开发者应提前规划域名、准备好 TLS 证书，并正确配置反向代理，确保客户端与服务端的 WebSocket 通信 稳定可靠。在实际开发中，要严格区分 开发工具测试 与 真机运行 的差异，避免因域名校验导致连接失败。通过合理的架构设计和心跳保活机制，可以构建高性能的小程序实时通信应用。