真机上wx.connectsocket报错“域名协议头非法”或连接失败，90%因域名未在后台“socket合法域名”栏正确配置（仅填纯域名如api.example.com，不可带wss://、端口或路径）、icp备案不合规、证书非可信ca签发或tls1.2+不支持、后端未透传upgrade/connection头及origin校验失败所致。
真机上 wx.connectSocket 报错“域名协议头非法”或连接直接失败，90% 是因为域名没配对、备案/证书不合规，或后端没正确处理 WebSocket 握手 —— 不是代码写错了，而是微信的校验链卡在了某一层。
微信后台“服务器域名”里不能填 wss:// 开头的地址
微信公众平台的「开发管理 → 服务器域名 → socket 合法域名」输入框只接受纯域名（如 api.example.com），**不允许带协议头、端口、路径**。填 wss://api.example.com 或 api.example.com:443 都会触发“该域名协议头非法”错误。
- 必须只填域名主体，比如
api.example.com，且该域名需已通过 ICP 备案（个人备案多数不被接受） - 备案主体要和小程序账号主体一致，或有明确授权关系
- 填完需重新提交审核，但配置生效是实时的，不用等审核通过才测试
- 如果用的是二级域名（如
ws.example.com），确保这个二级域名也单独完成备案
证书必须是可信 CA 签发、支持 TLS 1.2+、无中间证书缺失
微信真机强制校验证书链完整性。哪怕浏览器能打开 https://api.example.com，小程序仍可能因证书问题拒绝 wss:// 连接，报错类似 invalid http status 或直接静默失败。
- 用 SSL Checker 检查证书链是否完整，重点看“Intermediate Certificates”是否全部返回
- 自签名、Let’s Encrypt 的泛域名证书（如
*.example.com）在部分 iOS 微信版本中不稳定，建议用单域名证书 - Nginx 配置里要显式开启 TLS 1.2+：
ssl_protocols TLSv1.2 TLSv1.3;，禁用 TLSv1.0/1.1 - 避免使用云厂商默认的“免费 DV 证书”，有些未预埋进微信根证书库，换成 Sectigo 或 DigiCert 更稳妥
后端反向代理必须透传 Upgrade 和伪造 Origin
微信真机发起 wx.connectSocket 时，会携带一个形如 Origin: https://servicewechat.com/xxx/xxx/page-frame.html 的请求头。Spring Boot、Express 等框架默认会校验 Origin，不匹配就返回 403 或 500，导致握手失败（错误码 _code:20,_msg:invalid http status）。
- Nginx 反向代理配置中必须包含：
proxy_set_header Upgrade $http_upgrade;和proxy_set_header Connection "upgrade"; - 关键修复项：
proxy_set_header Origin "";或设为后端认可的白名单地址（如https://example.com） - 超时时间要拉长：
proxy_read_timeout 86400;，否则空闲连接会被代理主动断开 - 确认后端服务监听的是
https协议下的/ws路径，不是裸 HTTP；wss 不等于 “ws over https”，而是完整 TLS + WebSocket 协议栈
真机调试时勾选“不校验合法域名”只是临时绕过，不能解决根本问题
开发者工具或真机调试时勾选「不校验合法域名」，确实能让 wx.connectSocket 成功建立连接，但这只是跳过了微信客户端的域名白名单检查，并不绕过证书校验、Origin 校验或代理层限制。一旦上线或关闭该选项，所有问题立刻复现。
- 这个选项只适用于本地快速验证业务逻辑，**绝不能作为上线方案**
- 上线前务必关闭该选项，在真机上用正式包完整走一遍流程
- 如果关掉后仍失败，说明问题一定出在域名备案、证书、代理配置三者之一，而不是前端调用方式
- 注意：iOS 和 Android 微信对证书链容忍度不同，iOS 更严格，务必在两台真机上都验证
最常被忽略的一点：微信要求 WebSocket 域名必须和 request 域名分开配置，且必须填在「socket 合法域名」栏位下 —— 填错位置（比如填到 request 域名里）会导致真机完全不发起连接，连错误日志都不抛。
