小程序请求域名配置失败，绝大多数情况下是开发设置与服务器校验两个环节没对齐，按本文从登录后台到排查证书的路径走一遍,10分钟内就能定位问题。
先搞清“配置失败”到底卡在哪一步
在动手修改任何代码之前，建议先看一眼报错原文，微信开发者工具的控制台里会给出明确的errMsg提示，这些提示是问题定位的钥匙，常见的情况有两大类：域名校验不通过和网络请求直接被拦截。
- 如果是“url not in domain list”，说明小程序后台的request合法域名压根没添加,或者添加后没同步。
- 如果是“TLS version invalid”或“certificate verify failed”,说明服务器端的HTTPS证书有问题。
- 如果是“ERR_CERT_COMMON_NAME_INVALID”,说明证书的域名和你在小程序里填写的域名不匹配。
- 如果压根没反应，超时，那要考虑服务器防火墙或者小程序开发工具没勾选“不校验合法域名”。
小程序域名配置失败的三大常见原因
开发工具里勾选了“跳过校验”导致真机失效
很多开发者在本地调试时，图省事直接在微信开发者工具的“详情”->“本地设置”里勾选了“不校验合法域名、web-view（业务域名）、TLS版本以及HTTPS证书”，这种方法在模拟器里确实能跑通，但在真机预览或线上环境时会被强制拦截。
行业共识认为，这种情况下出现的域名配置失败，最容易被误判为后台配置错误，其实问题出在工具勾选项上，如果真机预览时请求失败，而开发者工具模拟器里一切正常,优先检查这个勾选项是否勾掉了。
request合法域名未正确填写或遗漏
在小程序管理后台的“开发”->“开发设置”->“服务器域名”里，需要分别配置request合法域名、socket合法域名、uploadFile合法域名、downloadFile合法域名，不少人只填了request，但业务里用到了wx.uploadFile上传图片，结果uploadFile合法域名是空的，同样会报“配置失败”。
每个域名都必须以https://开头，不支持IP地址和端口号，而且域名必须完成ICP备案，这里有个很容易踩的坑：如果同一个域名下同时用到了请求和上传，分属两个列表，需要分别填写,不要图省事只填一个。
HTTPS证书层级或协议版本不受支持
小程序要求服务器使用TLS 1.2或更高版本，如果服务器还停留在TLS 1.0或1.1，微信会直接拒绝请求。证书链不完整也是常见问题，服务器只部署了域名证书，而没有把中间证书（CA Bundle）一并配置,就会导致校验失败。
一步步排查并修复域名配置失败的实操流程
第一步：核对小程序后台的域名白名单
登录微信公众平台，进入“开发管理”->“开发设置”->“服务器域名”,这里需要逐项对照检查：
- request合法域名：检查是否有遗漏的域名,是否有拼写错误。
- socket合法域名：如果业务使用了WebSocket，确认这里填的是wss://开头。
- uploadFile合法域名：涉及文件上传必须单独配置。
- downloadFile合法域名：涉及文件下载必须单独配置。
配置文件修改后，通常5到10分钟生效，不需要重启小程序，但可能需要退出小程序重新进入，改名或新增域名时，建议在小程序管理后台点击“修改”后,清掉微信缓存再测试。
第二步：用开发者工具快速验证域名可用性
微信开发者工具提供了一个很实用的功能：在“工具”菜单下点击“域名信息”，可以查看当前小程序已配置的所有域名及状态，输入一个具体的请求URL,工具会直接告诉你这个域名是否在合法名单里。
在这个环节，不需要写任何代码，直接在“详情”->“域名信息”里粘贴你的API地址，就能看到校验结果，如果有问题，它会提示你不匹配的原因，比如证书过期、域名未备案、协议不支持等。
第三步：检查服务器端HTTPS配置是否完整
业内专家指出，相当一部分小程序请求域名配置失败的问题，根源在于服务器端配置不当，用浏览器直接打开你的API域名（比如https://yourdomain.com）,检查地址栏是否有小锁图标。
- 点击小锁图标，查看“连接是安全的”是否显示,这里能直观看到证书是否有效。
- 如果浏览器提示“不安全”，点击“证书”查看有效期,看是否过期。
- 查看证书是否由受信任的CA机构签发,自签名证书无法通过微信的校验。
- 用
openssl s_client -connect yourdomain.com:443（在本地终端执行）查看证书链是否完整。
第四步：设置里的“不校验合法域名”使用场景
这个选项不是完全不能勾，但要明确它的适用场景：仅限本地开发调试，在体验版或正式版环境中，即使勾选了也会被忽略，请求照样失败。 如果团队里其他成员各自开发不同模块，建议各自在开发工具中勾选“不校验合法域名”以方便联调，但在提交代码和体验版前必须取消勾选,验证一遍真实环境。
处理“小程序请求域名配置不生效”的特殊场景
刚配置完域名但请求依然失败
这可能是微信的缓存机制在捣乱，配置完合法域名后，在微信里彻底杀掉小程序进程，重新扫码进入，有时候还需要在微信的“发现”->“小程序”里长按小程序图标，选择“删除”后再搜索进入，开发者工具里也需要在“清缓存”菜单下，勾选“清除数据缓存”和“清除授权数据”。
域名已备案但依然报错
域名备案与域名校验是两回事，小程序合法域名校验只认“是否在小程序后台配置”以及“HTTPS证书是否有效”，域名备案是前提条件但不是充分条件，如果域名确实已备案，检查服务器是否开启了HTTPS监听端口,以及防火墙是否放行了443端口。
可以在本地用curl -v https://yourdomain.com看返回的响应头信息，如果证书报错会直接显示，这个命令很直观,不用安装额外工具。
开发版和正式版域名配置的区别
开发版和正式版共用一个域名白名单配置，不存在两套不同的设置，但开发时，如果你在开发者工具里勾选了“不校验合法域名”，开发版小程序可以访问任意域名；一旦取消勾选,开发版也需要走正式的域名校验逻辑。
很多团队遇到过这种情况：开发版一切正常，正式版却报域名错误，区别通常在于开发者工具里的勾选项和真机缓存，真机预览时,需要重新编译并确保用最新版代码。
配置域名时容易被忽略的细节
域名数量限制
小程序后台最多可以配置20个request合法域名，socket合法域名、uploadFile合法域名、downloadFile合法域名也都是独立的20个名额，如果业务域名较多，建议做一层域名收敛，比如通过网关统一入口,减少白名单数量。
不要使用IP地址和端口号
小程序强制要求域名形式，不支持IP直连，也不支持带端口号的URL，如果你的后端服务跑在8080端口的Tomcat上，必须通过Nginx做反向代理，将443端口映射到8080，也就是用https://abc.com 代替 https://abc.com:8080。
域名必须完成ICP备案
有朋友问过“小程序请求域名配置失败跟域名备案有关吗”，答案是关系很大，如果域名没有备案，即使加了白名单，请求也会被拦截，备案信息可以在工信部备案系统查询，也可以让你的服务器提供商协助确认备案状态，据工信部数据,域名备案审核周期一般为1到20个工作日。
小程序域名配置”的常见疑问解答
问：为什么我配置的域名是合法的，却仍然出现在小程序请求域名配置失败的情况？
答：可以先在“开发设置”->“服务器域名”里检查你的域名是否被误放在错误的分类下，如果确认无误，下一步用浏览器访问该域名的根路径，查看证书是否被系统信任，如果证书正常，检查代码里wx.request的url是否和后台一致，注意协议头一定得是https，不能是http，最后一个隐蔽问题：域名如果含有下划线或大写字母，也可能导致校验失败,建议全部使用小写字母。
问：小程序请求域名配置失效了怎么办？
答：部分开发者遇到过之前能正常使用、突然提示域名配置失效的情况，这时优先检查HTTPS证书是否过期，证书过期比较常见，尤其是免费版证书的有效期短，其次在微信公众平台“开发设置”页面，确认“域名信息”里的域名没有被误删，还有一个容易忽略的点：如果你的小程序同时关联了多个第三方平台，可能存在平台间配置覆盖的情况,需要留意是否有第三方服务商修改了域名配置。
结尾小结
小程序请求域名配置失败，核心排查路径就三条：后台白名单、HTTPS证书、开发者工具缓存，把这三点逐一对照检查，大多数问题都能在10分钟之内解决，配置完成后记得用真机预览测试一次,别留在模拟器里自嗨。