微信小程序合法域名怎么配置？，域名在哪里设置

微信小程序合法域名是上线前必须迈过的一道硬门槛，你的小程序里所有网络请求指向的服务器地址，必须是已在微信公众平台后台完成配置的HTTPS域名，否则正式版会出现请求全部被拦截的尴尬局面，这个规则没有商量余地，但开发阶段有官方后门可以绕过。

微信小程序合法域名配置：先搞懂规则再动手

合法域名规则是微信团队为保障用户数据安全设定的防火墙机制,小程序运行在微信的沙箱环境里，所有网络请求都得通过微信的接口去转发，域名不合法，请求直接拍死在半路。

哪些请求必须配置合法域名

域名配置不是一刀切,微信官方把网络请求分成了四类，每一类都有独立的配置入口：

• request合法域名：处理普通的HTTPS请求，比如你调用后端接口拉取商品列表、提交订单信息，走的就是这条通道
• socket合法域名：处理WebSocket长连接，做聊天室、实时客服、直播间弹幕这类功能时需要配置
• uploadFile合法域名：负责文件上传，用户传头像、发图片、传视频都走这个通道
• downloadFile合法域名：负责文件下载，比如导出Excel报表、下载语音包、拉取PDF合同

这四类域名都得是独立的合法域名,一个请求地址同时涉及多种类型，就得分别在对应类目下配置，大多数普通小程序只需要配request域名就够了，但使用场景不止于此，先想清楚你的业务形态再动手。

域名必须通过ICP备案

这条规则是硬性的,域名必须已完成ICP备案，备案信息可以在工信部备案系统查询到，不备案的域名在小程序后台根本提交不了，域名备案周期往往需要几个工作日到二十天不等，如果你正在筹备上线，建议第一时间把备案启动起来，别等开发完成才处理。

域名支持的协议版本也有讲究,request、uploadFile、downloadFile这三类要求必须使用HTTPS协议，TLS版本需要支持1.2及以上版本，开发环境下使用HTTP协议调试虽然可行，但上线前必须切换成HTTPS。

微信小程序合法域名怎么配置：后台操作完整路径

配置入口藏在微信公众平台的深层菜单里,操作路径如下：

开发管理 → 开发设置 → 服务器域名

进入后你会看到一个表单,里面有request合法域名、socket合法域名、uploadFile合法域名、downloadFile合法域名四个输入区，每个输入框都有数量限制，目前规则是

每个类目最多可以配置200个域名，对绝大多数开发者来说完全够用。

域名校验的过关方式

配置域名时微信会要求你验证域名的所有权,操作方式是这样的：

1. 微信后台会生成一个校验文件,文件名类似xxx.txt
2. 把这个文件放到你域名指向的服务器根目录下,访问路径应该是https://你的域名/文件名.txt
3. 回到后台点击“保存”，微信会发起访问验证，文件内容匹配就通过

如果你手头有多个域名要配置,每个都需要单独放校验文件，工作量不小但流程机械，照着做就行，校验通过后域名才正式生效，此后每次修改和新增域名也都会触发新的校验。

域名几个关键校验规则

配置合法域名时,有几个细节会让你踩坑：

• 域名必须是最简形式,不能带路径、带端口号、带参数
• 协议标识需要写完整,https://前缀不能少
• 域名仅支持一级域名或二级域名,不支持IP地址和localhost
• 已配置的域名不支持修改,只能删除后重新添加

第二条规则经常绊倒刚入门的新手,比如你把https://api.example.com/v1整个填进去，保存时直接被拒，正确做法是只填https://api.example.com，路径在代码里写。

开发阶段如何绕过合法域名校验

正式版跑起来之后,合法域名校验会严格把控每一笔网络请求，不过开发调试阶段，微信官方留了一个非常人道的开关：

打开微信开发者工具 → 右上角“详情” → 本地设置 → 勾选“不校验合法域名、web-view（业务域名）、TLS 版本以及 HTTPS 证书”

这个操作不需要任何代码改动,勾选后工具就会跳过域名校验，让你在开发环境里自由使用任意API地址，本地联调、mock数据、后端接口调试效率都能大幅提升。

需要注意的是,这个选项只对开发环境生效，而且只影响当前项目的本地调试状态，使用体验有差异的是：开发者工具上勾选了不校验合法域名，真机预览依然受校验约束，想用真机调试未配置的域名，得在预览时同样勾选“不校验合法域名”选项，扫描预览二维码后才会跳过校验。

另外有个坊间流传的做法是修改模拟器的hosts文件来绕过域名限制,这种做法可以针对特定域名调整指向，但工具本身的校验机制还在，并且模拟器配置与真机环境差异明显，排查问题容易踩坑，实操价值有限，不太推荐在这个方向上过度纠缠。

还有一个被广泛讨论的操作是在代码里直接禁用域名校验,开发者可以在app.js开头写入这样一段话：

// 仅用于开发调试，发布前请删除
wx.request({
  url: 'https://any-domain.com/api',
  success: res => {}
});

但这并不是取消校验的正路,小程序的域名校验是微信客户端层面的机制，不是几行JS代码能绕过的，与其在代码里做无用功，不如把本地校验开关利用好。

常见报错：不在以下request合法域名列表中

这是开发过程中出现频率最高的报错,也是大多数搜索者最头疼的问题，报错信息长这样：

https://api.example.com 不在以下 request 合法域名列表中，请参考文档：https://developers.weixin.qq.com/miniprogram/dev/framework/ability/network.html

只有真机预览和正式版才会触发这个报错,开发者工具一般不会提示，从错误信息就能看出，你还没在后台配置这个域名，或者你刚刚配置完但没生效。

排查思路按顺序走

遇到这个报错,建议按如下流程逐项排查：

1. 确认域名是否已经填入后台request合法域名列表,保存成功才算数
2. 确认域名ICP备案已通过,且备案主体与小程序主体一致或有关联
3. 确认域名是HTTPS协议,且TLS版本在1.2以上
4. 确认域名没有携带路径和端口号,例如错误的https://api.example.com:8080
5. 确认刚配置的域名已等待足够时间生效,后台配置修改后通常需要等待几分钟到十几分钟
6. 确认小程序基础库版本较新,比较古老的版本对某些HTTPS证书兼容性较差

90%以上报错都能从前三步找到原因，真的全都排查之后仍然报错，再去检查证书的信任链是否完整，中间证书缺失也会被微信拒绝。

验证域名配置是否生效的办法

修改后台域名配置后,别急着打开小程序，可以先用两个方法验证：

• 用浏览器访问https://你的域名，确认证书正常、页面可访问
• 在开发者工具清缓存后重新编译,等待几分钟再试

开发者工具右上角的“清缓存”按钮里有一个“清除数据缓存”选项，建议一并勾选“清除全部缓存”，确保旧的请求数据不影响调试结果。

合法域名和业务域名有什么区别

很多初次接触的开发者会对这两组概念犯迷糊,但它们在微信小程序体系里指向完全不同的配置区域，正规开发流程中，这两个配置都会用到。

合法域名管的是wx.request、wx.uploadFile等API的网络请求。
业务域名管的是web-view组件内嵌网页的跳转地址。

具体差异可以对照下表：

正常开发中,如果你没有使用web-view组件，业务域名可以完全忽略，但一旦涉及内嵌H5页面，业务域名不配置，用户触达时白屏没商量。

Q&A：微信小程序合法域名一定要备案吗

微信小程序合法域名一定要备案吗？

一定要,备案是小程序合法域名配置的前置条件，不备案的域名在后台提交时直接会被拦截，完整流程是先在服务器服务商处完成ICP备案，再在小程序后台配置域名，中间不能跳步，备案信息在工信部系统可查，时间周期一般在几个工作日到二十天之间，建议提前规划，微信官方文档也明确列出了已备案域名的要求。

配置了合法域名但小程序仍然请求失败怎么排查？

分三步走：第一步确认域名在后台配置生效，保存成功并且等待了足够时间；第二步确认域名证书完整可信，TLS版本达到1.2以上；第三步检查代码里的请求地址是否与后台配置的域名完全一致，大小写、斜杠、路径都不能有偏差，三步走完，绝大多数问题都能定位。

开发者工具不校验合法域名，真机预览是否也生效？

不生效,勾选不校验合法域名的选项只影响开发者工具本地模拟环境，微信客户端的域名校验机制依然严格存在，真机预览需要在预览时同样勾选不校验合法域名选项，正式版则完全没有豁免通道，这个设计意味着本地开发调通之后，发布前一定记得回后台把域名配置补齐。