微信小程序后台必须配置request、uploadFile、downloadFile三类合法域名，且socket合法域名需单独配置；manifest.json中urlCheck设为false可跳过本地调试校验，上线前须切回true并确保域名已配置且生效。
微信小程序后台必须配置的三类域名
uni-app 本身不管理域名白名单，所有域名授权都由微信平台强制执行。不配全这三类，uni.request、uni.uploadFile、uni.downloadFile 和 WebSocket 连接会直接失败，且错误信息极简（比如 request:fail net::ERR_CONNECTION_REFUSED），根本看不出是域名问题。
必须在微信公众平台「开发管理 → 开发设置 → 服务器域名」中逐项填写：
-
request合法域名：用于uni.request、uni.connectSocket（HTTP/HTTPS 接口） -
uploadFile合法域名：用于uni.uploadFile，必须和后端接收上传的接口协议、主机、端口完全一致（如https://api.example.com:443） -
downloadFile合法域名：用于uni.downloadFile，包括图片、PDF、音视频等资源链接
注意：socket 合法域名（WSS）是独立配置项，不能用 request 域名替代；所有域名必须以 https:// 或 wss:// 开头，不带路径，不带查询参数，端口必须显式写出（如 https://api.example.com:8443）。
manifest.json 中的 appid 和 urlCheck 设置影响域名校验时机
uni-app 打包时会读取 manifest.json 中的微信配置，其中两个字段直接影响域名检查行为：
-
"mp-weixin": { "appid": "wx1234567890abcdef" }—— 必填，否则 HBuilderX 无法生成小程序基础包结构 -
"setting": { "urlCheck": false }—— 关键开关。设为false时，本地调试（真机预览/开发者工具）跳过域名合法性校验；设为true（默认）则强制校验，哪怕只是本地联调也会报错request:fail errCode:1004 url not in domain list
开发阶段建议始终设为 false，上线前再切回 true 并确认所有域名已在后台配置完毕。这个开关只影响运行时校验，不影响最终包内容。
常见错误：Nginx 反向代理后域名仍被拒绝
很多人把后端服务部署在内网，用 Nginx 做 HTTPS 反代，以为只要配好 Nginx 就行了。但微信校验的是「请求发出时 URL 的 host 字段」，不是后端真实地址。
例如 Nginx 配置了：
location /api/ {
proxy_pass https://10.0.0.10:8080/;
proxy_set_header Host $host;
}
前端调用 uni.request({ url: 'https://api.example.com/api/user' })，微信只会检查 https://api.example.com 是否在 request 域名列表里——它不管你后端是不是 10.0.0.10。所以：
- 必须把
https://api.example.com加入微信后台的request合法域名 - Nginx 的
server_name必须和该域名完全一致 - SSL 证书必须覆盖该域名（不能是泛域名或 IP 证书）
- 如果用了 CDN，需确保 CDN 回源 Host 头正确，否则后端可能收不到请求
云函数中转不能绕过域名白名单
有人想用 uniCloud 云函数当代理，以为“前端请求云函数，云函数再请求第三方”，就能避开微信域名限制。这是误解。
微信校验的是「前端发起请求时写的 URL host」。如果你写的是：
uni.request({ url: 'https://third-party.com/data' })
哪怕这个请求实际被云函数拦截并转发，微信仍然会检查 https://third-party.com 是否在合法域名列表里——它不会识别你是否用了云函数。
正确做法是：
- 前端请求自己的云函数地址（如
https://xxx.service.tcloudbase.com/proxy） - 该地址必须已加入微信后台
request合法域名 - 云函数内部用
uniCloud.httpclient.request去调第三方，这部分不受微信限制
本质是把第三方域名从“前端直连”变成“服务端发起”，微信只管前端出口，不管服务端出口。
最易被忽略的一点：微信后台配置域名后，**不会实时生效**。新添加或修改的域名，通常需要 5–10 分钟才能同步到所有客户端环境，真机测试务必等够时间再验证，别一保存就立刻扫码测，大概率失败。
