一、开发者工具里明明是好的
你把接口写好,在电脑上 curl 一下,数据正常返回。打开微信开发者工具,页面上点一下按钮,列表也刷出来了,心里踏实了半截。顺手点「预览」,扫码用手机打开,同一个按钮按下去,页面空白,控制台甩出一句 request:fail url not in domain list。
于是开始怀疑人生:接口没改、地址没改、手机连的还是同一个网,怎么换个设备就不行了?有人去翻后端日志,翻半天一条记录都没有;有人把 https 改成 http 再试,照样不行;还有人反复编译、清缓存、重启工具,一个下午就这么过去了。
先把结论给你:这不是后端没开门,也不是业务逻辑写错了,是请求根本没走出手机。微信客户端在发请求之前拦了一道,拦它用的那本登记簿叫 request 合法域名,也就是大家口头说的域名白名单。开发者工具默认帮你把这道检查关掉了,真机预览没关,同一段代码自然两个结果。
二、把它想成小区门卫手里的登记本
你要去朋友家做客,朋友家灯火通明、门也开着。可小区大门的保安手里有一本登记簿,只放行上面写过的地址;你报的那个门牌号不在簿子上,人还没进小区就被请回去了。这时候去怪朋友「你怎么不开门」就找错对象了,他压根不知道你来过。
小程序的网络请求就是这个结构。你的后端是朋友家,微信客户端是小区大门,登记簿是小程序后台里那份 request 合法域名清单。浏览器里 fetch 一个地址,浏览器基本不会替你审查「这个域名配没配过」;但 wx.request 不一样,微信在客户端这一层先做校验,通过了才允许请求出网。
这个区别直接决定了一件事:白名单没通过时,后端日志里什么都不会有。请求没到过网关、没到过应用,你去后端翻访问日志、看监控曲线,全是白费力气。判断「拦在哪一层」比急着改东西更值钱,这也是后面所有排查的起点。
三、一次点击到后端,中间卡在哪一层
把链路铺开看,你就明白该去哪儿找证据了。
这张图要你注意那个分叉点:校验通过和不通过,从 C 就分成两条路了。失败那条根本没走到 D,所以后端日志、网关访问记录、接口耗时这些证据一律不会出现;而开发者工具的开关只作用在 C,它管不到真机。
四、把报错顺序亲手复现一遍
先看最小的一段页面代码,重点全在 fail 里那一行。
javascript
// pages/index/index.js:一个按钮,点一下查订单
Page({
data: { result: "还没请求" },
onTapQuery() {
wx.request({
// 必须是后台「服务器域名 → request 合法域名」里登记过的 https 地址
url: "https://api.example.com/v1/orders",
method: "GET",
// 主动设超时,否则失败时页面会一直转圈,看不出是快失败还是慢失败
timeout: 5000,
success: (res) => {
// 能进 success 只说明网络层通了,业务码还要自己判
this.setData({ result: "状态码 " + res.statusCode + ",数据 " + JSON.stringify(res.data) });
},
fail: (err) => {
// 关键一行:把 errMsg 原样打出来,白名单类问题全靠它定位
console.warn("请求失败:", err.errMsg);
this.setData({ result: "请求失败:" + err.errMsg });
},
});
},
});
xml
<!-- pages/index/index.wxml:按钮和一行结果,够用了 -->
<view>
<button bindtap="onTapQuery">查一下订单</button>
<text>{{result}}</text>
</view>
复现按这个顺序做,两次结果一对照就全清楚了:先在开发者工具「详情 → 本地设置」里确认勾着「不校验合法域名」,点按钮,进 success;然后把这个勾去掉,或者直接用真机预览,再点一次,进 fail,errMsg 就是那句域名未登记。地址一个字没动,变的只是那道校验有没有生效。
想再确认后端本身没毛病,在电脑上单独请求一次:
bash
# 绕过微信客户端直接请求同一个地址,用来区分「后端问题」和「白名单问题」
# -i 会把状态码和响应头一起打出来
curl -i https://api.example.com/v1/orders
curl 能返回 200,就说明后端活着、证书也能握手,问题锁死在小程序这一侧的校验。这一步别省:它把「该找后端」和「该改配置」干净地切成两半。
这张图要你注意 fail 是谁给的:它是微信客户端自己回调的,不是后端返回的错误响应。所以这类失败连 statusCode 都没有,res.data 更不用看,别按「接口报错」的思路去查返回体。
五、合法域名到底认什么
后台的入口在微信公众平台「开发管理 → 开发设置 → 服务器域名」,往 request 合法域名里填域名。它认的不是一条完整接口地址,而只是主机名:填了 api.example.com,后面 /v1/orders、/v1/users 都能请求,不用给每个接口配一次。这一点能省掉很多误会。
具体限制整理成表,改地址前逐行对一遍:
| 要求 | 可以这样写 | 不能这样写 | 违反之后的常见现象 |
|---|---|---|---|
| 协议 | https:// |
http:// |
域名未登记类报错 |
| 域名形式 | api.example.com 这类真实域名 |
IP 地址、localhost |
后台保存不了,或域名未登记 |
| 端口 | 不写端口,走默认 443 | :8080、:8443 |
域名未登记 |
| 证书 | 受信任机构签发、证书链完整、域名匹配 | 自签证书、缺中间证书 | 握手失败类报错 |
| 备案 | 国内主体用已备案域名 | 未备案域名 | 后台保存不了 |
| 修改次数 | 改前记下旧值,一次改对 | 反复来回试 | 次数用尽只能等下一个周期 |
证书那一行值得多说一句。域名配对了却报握手失败,通常不是白名单的问题,而是证书链没配全、证书和域名对不上,或者服务端 TLS 版本太旧。这类问题得让负责证书和网关的同事处理,你在小程序代码里怎么改 url 都救不回来。另外后台改域名有次数限制,别拿它当调试开关反复试。
六、用一段代码把校验顺序跑出来
「我明明配了域名,怎么还报错」是这一题里最常听到的一句。原因是校验不是一次性比对,而是逐层短路:协议、域名形式、端口、登记簿,一层过了才进下一层。用下面这段零依赖的 Node 脚本模拟一遍,不用装任何东西,存成 check-domain.js 后 node check-domain.js 就能跑。
javascript
// check-domain.js:模拟小程序「request 合法域名」的逐层校验顺序
// 零依赖,直接 node check-domain.js 运行;用来解释「配了域名为什么还报错」
// 已经登记在「服务器域名 → request 合法域名」里的域名
const allowList = ["api.example.com", "cdn.example.com"];
function checkDomain(rawUrl) {
let protocol, host, port;
try {
const u = new URL(rawUrl);
protocol = u.protocol; // 形如 "https:",带冒号
host = u.hostname; // 只有主机名,不含端口
port = u.port; // 显式写出的端口,空串表示用默认端口
} catch (e) {
return { ok: false, reason: "地址格式解析不了,先检查是不是漏写了协议" };
}
// 第 1 层:协议必须是 HTTPS,http 直接拦下
if (protocol !== "https:") {
return { ok: false, reason: "不是 HTTPS:只允许 https,http 一律不放行" };
}
// 第 2 层:不能是 IP,也不能是 localhost
const isIp = /^\d{1,3}(\.\d{1,3}){3}$/.test(host);
if (isIp || host === "localhost") {
return { ok: false, reason: "是 IP 或 localhost:后台根本填不进这种地址" };
}
// 第 3 层:不能自己带端口,默认 443 之外都不认
if (port !== "" && port !== "443") {
return { ok: false, reason: "带了端口 " + port + ":合法域名只认域名本身" };
}
// 第 4 层:域名要在登记本上
if (!allowList.includes(host)) {
return { ok: false, reason: "域名没登记:合法域名列表里没有 " + host };
}
return { ok: true, reason: "放行,请求这才真正发出去" };
}
// 六种新人最常写出来的地址
const cases = [
"https://api.example.com/v1/orders",
"http://api.example.com/v1/orders",
"https://192.168.1.20/v1/orders",
"https://localhost:8080/v1/orders",
"https://api.example.com:8443/v1/orders",
"https://api.other.com/v1/orders",
];
for (const c of cases) {
const r = checkDomain(c);
console.log((r.ok ? "放行 " : "拦下 ") + c);
console.log(" " + r.reason);
}
六个地址跑出来的结果:
| 地址 | 结果 | 卡在第几层 |
|---|---|---|
https://api.example.com/v1/orders |
放行 | 全部通过 |
http://api.example.com/v1/orders |
拦下,不是 HTTPS | 第 1 层,协议 |
https://192.168.1.20/v1/orders |
拦下,是 IP | 第 2 层,域名形式 |
https://localhost:8080/v1/orders |
拦下,是 localhost | 第 2 层,域名形式 |
https://api.example.com:8443/v1/orders |
拦下,带了端口 8443 | 第 3 层,端口 |
https://api.other.com/v1/orders |
拦下,域名没登记 | 第 4 层,登记簿 |
这张图要你注意它是逐层短路的:只有前面全过了,才会走到最后那个「在不在清单里」的判断。所以「我明明配了域名还报错」,多半是卡在前三层,压根没轮到比对登记簿。
七、几个特别容易踩的坑
把开发者工具的开关当成配置。 那个勾只是本机调试用的,关掉它不影响后台登记簿,也不影响真机。很多人在工具里跑通就以为联调结束,直到提测才被真机打回来。
拿本地地址硬上真机。 localhost、127.0.0.1、办公室内网 IP 都填不进后台,因为它们不是可备案的公网域名。本地阶段要么在工具里关校验,要么走一台有正式域名、证书齐全的测试环境,别指望手机能直接访问你笔记本上起的服务。
把 fail 的内容丢掉。 只写 fail: () => {} 或者干脆不写 fail,页面就只剩「没反应」,等于自己把唯一的线索扔了。errMsg 是关键证据,先看它再动手:
| fail 里的 errMsg | 它其实在说 | 该改哪一层 |
|---|---|---|
request:fail url not in domain list |
地址没通过域名校验,含 http、IP、端口、未登记 | 配置层补合法域名,或代码层改 url |
request:fail ssl hand shake failed |
TLS 握手没成,证书链或服务端 TLS 版本有问题 | 依赖与环境层:换受信任证书、补全证书链 |
request:fail timeout |
域名已经放行,但对面没在超时内回 | 先查后端与网络,别再动白名单 |
改完后台不重新进小程序。 域名配置由客户端拉取,手机上可能还留着旧的那份。改完重新编译预览,必要时把手机上原来的小程序删掉重新进一次,再判断有没有生效。
本地调试有三种正规做法,按阶段选,别混着用:
| 方式 | 怎么开 | 校验还生效吗 | 适合什么时候 |
|---|---|---|---|
| 开发者工具关校验 | 详情 → 本地设置 → 勾选不校验合法域名 | 不生效 | 本机写代码阶段,最快 |
| 真机打开调试模式 | 预览版菜单里打开调试 | 部分跳过,别当上线依据 | 想在手机上看真实布局时 |
| 配好域名走正式链路 | 后台登记已备案的 https 域名 | 生效 | 提测、体验版、上线前 |
八、出问题时,下一步往哪走
把前面的判断串成一条排查路径,遇到「点了没数据」照着往下走就行,不用每次重新想。
这张图要你注意最后那几道菱形。改生产环境的服务器域名属于会影响全部用户的操作,正确姿势是写出建议方案,说明影响面、目标值和回滚点,交给负责人人工确认、走完审批再执行,并且执行前真的留着能退回去的旧配置。别自己登录后台顺手就改,也别拿正式域名当调试开关来回试。
还有一条流程上的坑:为了查问题把预览报错截图、响应内容直接甩到群里,很容易把敏感信息带出去。手机号写成 138****5678,Token 只留前几位如 sk-1***,客户名称和地址一并隐去,再往外发。
九、想真正弄明白,按这个顺序练
第一步,把第四节那两个文件照着敲一遍,在开发者工具里把「不校验合法域名」勾上、去掉各跑一次,盯着 fail 里那句 errMsg 看清楚。两种结果一对照,「校验在哪一层」这件事就不用背了。第二步,把第六节的脚本存下来跑一遍,然后自己往 cases 里加地址,比如带个查询参数、换个大写主机名、写个 IPv6,猜一猜会卡在第几层,再拿输出对答案。第三步,找一台有正式域名和证书的测试环境,把整条正式链路走通,体会一下「配好了就再也不用管」是什么感觉。
工作里还有两条比记住规则更值钱。一条是联调时先给证据:把 url、errMsg、curl 的结果三联发过去,别只说一句「我这边连不上」,沟通成本立刻降下来。另一条是分清环境,本地怎么方便怎么来,提测和上线前必须按正式链路验一遍,别把调试开关的宽松当成线上的默认状态。慢慢你会发现,这类问题真正难的不是配置在哪儿填,而是先判断清楚它拦在哪一层;养成先看证据、再定哪一层、最后动手的习惯,比记住十条规则都管用。
十、最后总结
回到开头那个下午。让人耗掉半天的不是接口有多难,是一直在后端找一条根本没发出去的请求。小程序和浏览器最大的差别,在于 wx.request 发请求之前,微信客户端会先拿地址去比对那份 request 合法域名清单;校验在客户端完成,不通过就直接回调 fail,请求连出网的机会都没有,所以后端日志里空空如也,而开发者工具默认关掉了这道检查,真机预览却会认真执行,同一段代码才有了两个结果。
把顺序记住就够了:先用 curl 确认后端活着,再读 fail 里的 errMsg,然后按「协议、域名形式、端口、登记簿」这四层逐层对一遍,绝大多数「配了还报错」都停在前三层。改配置时记得合法域名是域名级而不是接口级,填一次主机名后面的路径都通用;证书链和 TLS 版本属于另一层的事,得找负责网关的同事,改 url 救不了。回去可以把那两个文件在工具里跑一遍、把校验脚本加上几个自己编的地址试试,再给自己负责的小程序画一张从点击到后端的链路图,下次再遇到「点了没数据」就能几分钟说清是哪一层的事。真要动生产环境的域名,写方案、请负责人确认、走完审批并留好回滚点,别自己直接改;往外发报错截图前把手机号和凭证打码。工具给你的是证据,判断靠的还是那句老话------先看清楚,再动手。