小程序 WebSocket 连接报错：域名未配置在合法 socket 域名列表中

Question

小程序 WebSocket 连接报错“域名未配置在合法 socket 域名列表中”，是最常见的线上连接失败原因之一。该错误并非代码逻辑或网络问题，而是微信小程序强制的安全策略：所有 `wx.connectSocket()` 使用的 `wss://` 域名，必须提前在【微信公众平台 → 小程序后台 → 开发管理 → 开发设置 → 服务器域名】中，准确填写至「WebSocket 合法域名」栏（注意：仅支持 `wss://`，不支持 `ws://`；不支持 IP、端口、路径或通配符）。常见疏漏包括：误填 HTTP 域名、遗漏 `wss://` 协议头、使用测试环境域名未同步更新线上配置、或未点击「保存」并等待 5 分钟生效。配置后仍报错？需确认域名已备案、SSL 证书有效（wss 要求 HTTPS 级别证书），且服务端 WebSocket 服务正常响应。开发阶段可临时用 `localhost` 或 `127.0.0.1` 调试，但真机预览/体验版必走白名单校验。

Answer 1

```html

一、现象层：错误表征与典型报错日志

真机调试或体验版中调用 wx.connectSocket({ url: 'wss://api.example.com/ws' }) 时，控制台抛出明确错误：“域名未配置在合法 socket 域名列表中”。该错误不触发 onOpen/onError 回调，而是直接在 wx.connectSocket 同步阶段阻断连接，且无 HTTP 状态码或底层网络日志——这是微信客户端 SDK 在 JSBridge 层实施的白名单预检（Pre-flight Check），属于策略性拦截，非运行时异常。

二、策略层：微信安全模型的强制约束机制

• 协议刚性：仅接受 wss://（TLS 加密 WebSocket），ws://、http://、https:// 均被拒绝；
• 域名纯度要求：只允许二级及以上已备案域名（如 wss://chat.yourcompany.com），禁止含端口（:443）、路径（/v1/ws）、查询参数、IP 地址（wss://192.168.1.100）、通配符（wss://*.yourcompany.com）；
• 环境隔离性：开发版、体验版、线上版共用同一套「WebSocket 合法域名」配置，无环境变量切换能力。

三、配置层：后台操作全流程与高频陷阱

步骤	正确操作	典型错误
① 进入路径	微信公众平台 → 小程序 → 开发管理 → 开发设置 → 服务器域名	误入「request 合法域名」或「uploadFile 合法域名」栏位
② 填写格式	wss://api.yourapp.com（无路径、无端口、无协议外字符）	填入 https://api.yourapp.com 或 wss://api.yourapp.com:8080
③ 生效确认	点击「保存」→ 等待 ≥5 分钟 → 清除小程序缓存后重试	保存后立即测试，或未重启开发者工具/手机微信进程

四、验证层：多维度交叉诊断清单

1. ✅ 使用 curl -I -v https://api.yourapp.com 验证 SSL 证书链完整、有效期覆盖、且由受信 CA 签发（非自签名）；
2. ✅ 通过 openssl s_client -connect api.yourapp.com:443 -servername api.yourapp.com 检查 SNI 支持与证书绑定；
3. ✅ 用浏览器访问 https://api.yourapp.com 确认域名已备案（工信部公示可查），且无 HTTPS 混合内容警告；
4. ✅ 在服务端启用 WebSocket 健康检查端点（如 GET /ws/health），返回 200 + {"status":"up"}；
5. ✅ 使用 wscat -c wss://api.yourapp.com/ws（需安装 wscat）从公网机器直连，排除 Nginx/CDN 层 WebSocket 升级失败。

五、架构层：生产环境 WebSocket 可靠性设计建议

graph LR
  A[小程序客户端] -->|1. wx.connectSocket| B{域名白名单校验}
  B -->|通过| C[SSL/TLS 握手]
  B -->|失败| D[立即报错 “域名未配置…”]
  C -->|成功| E[HTTP Upgrade 请求]
  E -->|服务端返回 101| F[WebSocket 数据帧通信]
  E -->|服务端拒绝| G[触发 onError]
  style D fill:#ff9999,stroke:#333
  style F fill:#99ff99,stroke:#333

六、演进层：面向未来的工程化规避策略

对于中大型团队，建议构建「域名配置即代码（Domain-as-Code）」流程：
① 将合法域名列表纳入 CI/CD 流水线（如 GitHub Actions 检查 PR 中 config/domains.json 是否匹配平台 API 返回值）；
② 开发阶段强制使用 wx.connectSocket({ url: process.env.NODE_ENV === 'development' ? 'wss://localhost:8080' : WSS_PROD_URL })，配合 project.config.json 的 miniprogramRoot 动态注入；
③ 上线前自动调用 微信开放接口 getSecurityDomain 获取当前生效域名，比对部署配置一致性。

```