真机 wx.connectSocket 报“域名协议头非法”主因是微信后台 socket 合法域名配置错误：仅支持纯域名（如 ws.example.com），禁用协议/端口/路径；须主体备案一致、独立ICP备案、完整可信CA证书链；后端需透传Upgrade头并白名单servicewechat.com Origin；开发工具不等同真机，填完域名必须重新提交小程序版本生效。
真机上 wx.connectSocket 报“域名协议头非法”或直接静默失败，90% 是因为「socket 合法域名」填错了——不是代码问题，是微信后台配置卡死了握手流程。
socket 合法域名只认纯域名，不接受任何协议/端口/路径
微信公众平台的「开发管理 → 服务器域名 → socket 合法域名」输入框有严格格式限制：
- ✅ 正确写法：
api.example.com、ws.example.com（二级域名需单独备案） - ❌ 错误写法：
wss://api.example.com、api.example.com:443、wss://api.example.com/ws - 填错会直接触发“域名协议头非法”错误，且不提示具体哪部分违规
- 即使你用的是
wss://ws.example.com:443/mqtt，白名单也只填ws.example.com，其他全部丢弃
备案主体、域名层级、证书链必须三者对齐
光填对格式还不够，微信真机会逐层校验：
微信小程序 TabBar 图标生成
下载
微信小程序 TabBar 图标生成技能，使用 Python PIL 绘制简约几何图标（未选中灰、选中绿），自动写入 app.json 配置。适用于“生成 tabBar 图标”、“底部菜单栏图标”、“tab 图标”等指令。
- 备案主体必须与小程序账号主体一致，或提供加盖公章的授权书（个人备案基本无效）
- 若用
ws.example.com，它本身必须完成独立 ICP 备案（不能只备example.com） - 证书必须由可信 CA 签发，且返回完整证书链（中间证书缺失会导致“invalid http status”，用 SSL Checker 验证）
- Let’s Encrypt 泛域名证书（
*.example.com）在部分 iOS 微信版本中握手失败，建议改用单域名证书
后端反向代理必须透传 Upgrade 头并处理 Origin 校验
微信真机发起 WebSocket 握手时，会携带类似 Origin: https://servicewechat.com/xxx/xxx/page-frame.html 的请求头。很多后端框架默认拦截该 Origin：
- Nginx 必须显式配置：
proxy_set_header Upgrade $http_upgrade;和proxy_set_header Connection "upgrade"; - Spring Boot 默认校验 Origin，需禁用或白名单：
registry.addEndpoint("/ws").setAllowedOrigins("https://servicewechat.com", "https://example.com") - Express + ws 库需手动忽略：
verifyClient: ({ origin }) => true（仅测试环境） - 未处理时，服务器返回 403 或 500，微信解析为 “invalid http status” 并终止连接
开发工具能连 ≠ 真机能连，别跳过真机验证环节
开发者工具使用浏览器内核，对 TLS 版本、证书信任链、Origin 校验都更宽松；真机运行的是微信自研 JS 引擎，执行全链路安全检查：
- 开发工具支持自签名证书 +
ws://，真机强制要求wss://+ 可信 CA 证书 + TLS 1.2+ - 开发工具可能忽略
onOpen未触发的问题，真机下success回调不代表连接就绪，必须等onOpen才能发心跳或消息 - 哪怕后台已填好域名、证书也正常，仍需用真机扫码调试确认 —— 开发工具的“成功”只是假阳性
最常被忽略的一点：填完 socket 合法域名后，必须重新提交小程序版本（哪怕只是提审测试版），否则新域名不会进入审核沙箱，真机调试依然走不通。
