小程序域名白名单必须在微信公众平台后台配置，未添加域名时，小程序发起的网络请求会被微信客户端直接拦截，并返回“url not in domain list”等错误，无法正常调用后端接口。 配置入口在“开发管理-开发设置-服务器域名”，需管理员扫码，每月修改次数有限。
小程序域名白名单配置步骤：从后台到校验的完整路径
登录微信公众平台找到配置入口
- 使用小程序管理员账号登录微信公众平台（mp.weixin.qq.com），扫码进入。
- 左侧菜单点击“开发” -> “开发管理” -> “开发设置” -> “服务器域名”。
- 首次配置或修改时,需要管理员扫码验证身份。
- 每月可修改次数有限,通常为5次，具体以页面显示为准，建议一次性规划好域名再提交。
添加域名时的硬性规则
行业共识认为,域名必须满足以下条件才能保存成功：
- 协议必须是HTTPS，不支持HTTP，如果后端接口只有HTTP，需要先升级。
- 不能使用IP地址，不能填
0.0.1或localhost，也不能带端口号（默认443）。 - 域名必须完成ICP备案，且备案主体最好与小程序主体一致，境外域名通常无法备案，不能直接使用。
- 不能带路径，例如
https://api.example.com/v1只能填https://api.example.com。 - 不支持通配符，必须填写具体的子域名，比如
api.example.com。 - 每个类型（request、socket、uploadFile、downloadFile）可分别配置，据微信官方文档，每个类型最多20个域名。
配置后的校验与生效
保存后立即生效,但已发布的小程序可能需要用户重新打开才加载新配置，在微信开发者工具中，如果未勾选“不校验合法域名”，wx.request会直接报错，可以用以下命令测试服务器TLS版本是否达标：
openssl s_client -connect api.example.com:443 -tls1_2，如果握手失败，说明服务器不支持TLS 1.2，微信会拒绝请求。
未添加域名会报错吗？不同场景下的实际表现
真机与线上环境的报错
未添加域名时,真机和线上正式版都会报错，常见提示：
request:fail url not in domain listrequest:fail invalid domainuploadFile:fail url not in domain listdownloadFile:fail url not in domain list
请求不会到达服务器,直接在微信客户端被拦截，用户端看到的可能是“网络请求失败”，但开发者可以在vConsole或小程序后台日志中看到详细原因，业内专家指出，真机环境不会给任何绕过机会，必须提前配置。
开发者工具中的例外
微信开发者工具提供“不校验合法域名、web-view（业务域名）、TLS版本以及HTTPS证书”选项，勾选后，本地开发可以绕过白名单，但这个选项仅用于开发调试，真机预览、体验版、正式版均无效，很多开发者本地跑得通，一上真机就报错，原因就在这里。
哪些请求不受白名单限制
- 云开发调用云函数,不经过域名白名单。
- 微信提供的原生API（登录、支付、分享）不需要配置。
- 小程序内使用
<web-view>加载的网页，受“业务域名”限制，不是服务器域名。 - 支付后的异步通知是服务器端行为,与小程序前端白名单无关。
微信小程序服务器域名怎么设置？与业务域名的区别对比
三种域名的核心区别
| 类型 | 配置位置 | 作用 | 是否需要备案 |
|---|---|---|---|
| 服务器域名 | 开发设置-服务器域名 | 小程序前端发起网络请求 | 是 |
| 业务域名 | 开发设置-业务域名 | web-view加载的网页 | 是 |
| 网页授权域名 | 开发设置-网页授权域名 | 公众号网页授权 | 是 |
服务器域名只需填写域名,不需要上传校验文件，业务域名则需要下载校验文件，放到网站根目录，确保能通过https://你的域名/校验文件名.txt访问，网页授权域名主要用于公众号H5，与小程序前端请求无关。
配置顺序与常见坑点
- 先配置服务器域名,再配置业务域名，服务器域名影响所有网络请求，优先级最高。
- 业务域名校验文件如果被服务器重写规则拦截,会导致校验失败，可以临时加一条Nginx规则：
location = /校验文件名.txt { root /网站根目录; }。 - 如果使用第三方服务,要确认对方域名已备案且支持HTTPS，部分云服务商提供的测试域名未备案，不能直接填入。
- 修改域名后,旧版本小程序可能仍缓存旧配置，建议发布新版本，并提醒用户更新。
小程序域名白名单配置需要额外付费吗
配置动作本身不收费,但域名注册通常每年几十元，SSL证书有免费和付费选项，ICP备案免费但需要时间，如果使用云服务器，还会产生服务器费用，无论你在北京还是深圳，配置流程完全一致，但备案审核周期各地略有差异，近年来小程序安全要求趋严，免费证书也需选择受信任的CA机构，自签名证书无法通过。
小程序域名白名单配置常见问题Q&A
未添加域名会报错吗？具体报错代码是什么？
会报错,常见错误码和提示：request:fail url not in domain list、request:fail invalid domain，在微信开发者工具控制台可以看到详细原因，如果服务器证书过期或TLS版本过低，也会报错，但提示为request:fail ssl handshake error，需要检查证书和TLS配置。
域名备案对小程序白名单有影响吗？
有影响,微信要求服务器域名必须完成ICP备案，否则无法保存，境外域名通常无法备案，因此不能直接用于小程序，如果使用香港或海外服务器，需要先解决备案问题，或者通过国内中转服务器代理请求，备案信息可以在工信部网站查询，未备案域名提交时会提示“域名未备案”。
小程序域名白名单最多可以配置多少个？
据微信官方文档,每个类型（request、socket、uploadFile、downloadFile）最多可配置20个域名，业务域名和网页授权域名也各有数量限制，超过后需要删除旧域名才能添加新域名，未备案域名无法通过微信公众平台的保存校验。
首发原创文章，作者：王坚，如若转载，请注明出处：https://idctop.com/article/764434.html
