socket合法域名是什么，如何配置socket合法域名？

“socket合法域名”是微信小程序连接WebSocket服务器的强制门槛，配置位置在微信公众平台后台，必须使用已备案域名且开启TLS加密，否则真机调试永远连不上。

先给你一个结论：无论你在开发者工具里怎么改代码，只要没有在小程序管理后台把服务器地址写进socket合法域名列表，真机一运行就会报错，这个问题的解法不在代码层，而在配置层，下面按从原理到操作的顺序,把这条链路上所有坑都走一遍。

socket合法域名怎么配置：前置条件与后台操作路径

配置前先自查三个硬性条件

• 域名已备案：大陆服务器要求ICP备案，接入微信平台时系统会自动校验，用香港或海外服务器时，也要先确认能否通过微信的实名校验,多数情况下同样需要备案号。
• 协议必须是WSS：微信强制要求WebSocket连接走wss://加密协议，如果你的服务端只暴露了ws://普通端口,配置后依然会被拦截。
• TLS版本不低于1.2：这是微信官方文档的硬性要求，老服务器上如果还开着TLS 1.0，真机会直接握手失败，返回类似errno:600001的异常。

三个条件都满足后,进入正式配置环节。

后台设置的唯一入口

登录微信公众平台（mp.weixin.qq.com）,按照下面这个路径操作：

• 左侧菜单找到“开发管理”
• 点击“开发设置”
• 页面中部找到“服务器域名”一栏
• 点击“修改”，在“socket合法域名”输入框里填写你的域名

输入时不需要手动加http或ws前缀，直接填域名主体即可，如果你用了非标准端口，比如8080，要把端口也写进去，格式类似chat.example.com:8080。

保存后会有一个平台校验过程，正常情况下5分钟左右生效，这里提醒一句：旁边那个“不校验合法域名”的开关，只是开发调试用的逃生通道，不是正经配置，真正的线上版本,审核时都会检查你的socket合法域名列表。

域名填写时的格式细节

• 一个域名可以同时挂在多个小程序名下，但每个小程序独立审核
• 域名主体不能是IP地址，不能是localhost
• 同一域名下多个端口，需要分别配置，除非都用443端口
• 配置后域名会出现在一个已知的列表中，

  

  不会再额外收取平台费用

做到这一步，你的基础配置就完成了，但很多开发者卡在“配置完还是连不上”,问题往往出在下面这种地方。

小程序socket合法域名在哪设置：绕开三个高频踩坑点

开发者工具里勾了“关闭校验”，以为万事大吉

打开微信开发者工具的“详情”设置，有一个“不校验合法域名”的选项，勾选后本地开发确实能通，这是为了方便本地联调，但真机预览、体验版和正式版都会忽略这个开关，大部分新手都栽在这儿，以为代码没问题,其实是配置没进后台。

把IP地址或内网地址填进了socket合法域名

微信规定socket合法域名必须是公网域名，且域名解析到的IP不能是内网地址，如果是自建服务，很多人把168.x.x写进去，结果平台校验直接打回，解决办法是用内网穿透工具或者云服务器公网IP,同时域名解析到公网地址。

忽略了证书链的完整性

即使你用了HTTPS证书，如果证书链不完整，服务端的SSL握手也会失败，行业内不少开发者反馈，用Let's Encrypt免费证书时，需要把fullchain.pem配置完整，只填cert.pem会导致部分安卓机型无法连接，这个问题排查起来比较隐蔽,因为iOS和开发者工具可能表现正常。

如果你也遇到“后台配好了，真机还是连不上”的情况，优先检查上面三个点,接下来聊一个更实际的问题。

socket合法域名需要收费吗？费用藏在证书与备案里

很多开发者第一次接触这个概念时，会以为这是微信的付费服务。微信平台本身不收取任何socket合法域名的配置费用，后台添加域名是免费的，但“免费”只指平台侧,配套成本需要你自己承担。

成本主要产生在三个环节

• 域名注册：一年几十元到上百元不等，取决于后缀和注册商
• SSL证书：有免费版（如Let's Encrypt、酷番云免费证书），也有付费增强型证书，费用从几百到几千元每年
• 服务器带宽：WebSocket是长连接，并发连接数会影响服务器选型，这部分成本按业务规模浮动

所以你在和一些小程序开发团队议价时，他们报的价格里通常已经隐含了证书和域名的维护成本，如果接到一个“socket合法域名怎么配置”的私活，这个配置操作本身不值钱，

值钱的是TLS调优、证书续期和连接稳定性保障。

业内专家指出，相当一部分的socket连接失败案例，最后都追溯到证书更新不及时导致的过期问题，免费证书有效期普遍只有90天,需要有手动或自动续期的机制。

把成本问题想清楚之后，一个常见的混淆点浮出水面：socket合法域名和其他合法域名到底是不是一回事。

socket合法域名和request合法域名，两者有什么区别

在小程序后台的服务器域名设置里，有request、uploadFile、downloadFile、socket四类合法域名，很多人会把request合法域名和socket合法域名搞混，以为都是“填个域名”,实际定位完全不同。

从技术原理上理解：request是常规的HTTP请求，一次请求一次响应；而socket建立的是全双工通道，服务器可以主动向客户端推数据，行业共识认为，需要实时性的功能才使用socket，如果只是拉取数据，优先用request,这样能大幅减少连接资源的占用。

配置时的数量上限差异

• 一个申请的合法域名个数上限有限，具体以微信后台提示为准
• socket合法域名与request合法域名分别计算，互不占用名额
• 如果一个域名既用于请求又用于WebSocket，两个分类下都要分别配置

明确了区别,最后一步就是验证你的配置到底通没通。

配置之后怎么验证socket合法域名真的生效了

推荐按以下几个步骤实测

• 在微信开发者工具中勾选“不校验合法域名”，用wss://地址先做一次本地连接，确认服务端能通
• 取消勾选该选项，

  

  重新编译项目，此时工具会执行域名白名单校验，如果配置正确，编译过程不报错

• 点击“真机调试”，用手机预览页面，打开调试器的Network面板观察WebSocket帧
• 把按钮和日志测试全部做一遍，高位帧能正常收发，才算真正配置成功

常见验证命令整理

• 在服务器上用openssl s_client -connect yourdomain.com:443 -tls1_2检查TLS版本是否支持
• 用浏览器的控制台建立WebSocket连接模拟测试，很多情况下这能快速定位服务端问题
• 查看小程序后台“开发设置”中域名列表，确认保存时间点是最近一次修改

如果真机调试时仍然连接失败，把报错信息完整贴到微信开发者社区的搜一搜里，通常能找到相同场景的问答记录，也可以检查一下基础库版本，老版本的基础库对TLS 1.3的支持有差异,升级基础库往往能解决一类潜在兼容问题。

常见问题整理

socket合法域名配置后多久生效？

微信公众平台官方给出的说法是配置后立即生效，但多数开发者实测存在1到5分钟的分发延迟，在配置完成后，建议你先关闭开发者工具，重新打开项目再做真机测试，可以尽量避免缓存导致的“看起来没生效”假象，移动端遇到白屏或连接超时,也优先等5分钟再重试。

socket合法域名端口怎么填写？

如果你的WebSocket服务跑在443端口，域名后不需要写端口，系统默认使用443，如果服务跑在其他端口，比如8080或9002，必须在域名后面用冒号跟上端口号，例如wss://chat.example.com:8080。注意每个不同端口都需要单独添加一条记录，同一个域名不能覆盖所有端口，非443端口对某些网络运营商环境不友好，个别用户局域网下可能无法连接，这种情况不是配置问题,是网络策略限制。

小程序报错“URL not in domain list”怎么解决？

这个报错是典型的合法域名校验失败，核心原因就是你把socket合法域名填错了位置，先检查是否填进了request合法域名，而不是socket合法域名类别下，再确认你使用的地址是wss://开头，而不是https://，如果这两处都没问题，删掉后台该域名重新添加一次，然后等待5分钟并重启开发者工具，多数情况下做完这三步,报错就会消失。