[端与游戏开发手记] 小程序第一次调接口,卡在域名白名单的那半天

一、开发者工具里明明是好的

你把接口写好,在电脑上 curl 一下,数据正常返回。打开微信开发者工具,页面上点一下按钮,列表也刷出来了,心里踏实了半截。顺手点「预览」,扫码用手机打开,同一个按钮按下去,页面空白,控制台甩出一句 request:fail url not in domain list。

于是开始怀疑人生:接口没改、地址没改、手机连的还是同一个网,怎么换个设备就不行了?有人去翻后端日志,翻半天一条记录都没有;有人把 https 改成 http 再试,照样不行;还有人反复编译、清缓存、重启工具,一个下午就这么过去了。

先把结论给你:这不是后端没开门,也不是业务逻辑写错了,是请求根本没走出手机。微信客户端在发请求之前拦了一道,拦它用的那本登记簿叫 request 合法域名,也就是大家口头说的域名白名单。开发者工具默认帮你把这道检查关掉了,真机预览没关,同一段代码自然两个结果。

二、把它想成小区门卫手里的登记本

你要去朋友家做客,朋友家灯火通明、门也开着。可小区大门的保安手里有一本登记簿,只放行上面写过的地址;你报的那个门牌号不在簿子上,人还没进小区就被请回去了。这时候去怪朋友「你怎么不开门」就找错对象了,他压根不知道你来过。

小程序的网络请求就是这个结构。你的后端是朋友家,微信客户端是小区大门,登记簿是小程序后台里那份 request 合法域名清单。浏览器里 fetch 一个地址,浏览器基本不会替你审查「这个域名配没配过」;但 wx.request 不一样,微信在客户端这一层先做校验,通过了才允许请求出网。

这个区别直接决定了一件事:白名单没通过时,后端日志里什么都不会有。请求没到过网关、没到过应用,你去后端翻访问日志、看监控曲线,全是白费力气。判断「拦在哪一层」比急着改东西更值钱,这也是后面所有排查的起点。

三、一次点击到后端,中间卡在哪一层

把链路铺开看,你就明白该去哪儿找证据了。

flowchart LR A["页面点下按钮"] --> B["wx.request 组装地址与参数"] B --> C["微信客户端做合法域名校验"] C -->|"校验通过"| D["公网 HTTPS 传输"] D --> E["后端接口处理并查数据"] E --> F["返回响应,进 success 回调"] C -->|"校验不通过"| G["直接回调 fail,请求不出网"] G --> H["页面显示请求失败"] K["开发者工具的不校验合法域名开关"] -.->|"只影响这一层"| C

这张图要你注意那个分叉点:校验通过和不通过,从 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,就说明后端活着、证书也能握手,问题锁死在小程序这一侧的校验。这一步别省:它把「该找后端」和「该改配置」干净地切成两半。

sequenceDiagram participant P as &#34;页面&#34; participant W as &#34;微信客户端&#34; participant S as &#34;后端服务&#34; P->>W: 调用 wx.request 并传入地址 W->>W: 读取已登记的合法域名清单 W-->>P: 校验未通过,回调 fail Note over W,S: 请求没有出网,后端收不到

这张图要你注意 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 层,登记簿
flowchart TD A[&#34;拿到一个请求地址&#34;] --> B{&#34;协议是 https 吗&#34;} B -->|&#34;否&#34;| X[&#34;拦下:只允许 HTTPS&#34;] B -->|&#34;是&#34;| C{&#34;是 IP 或 localhost 吗&#34;} C -->|&#34;是&#34;| X2[&#34;拦下:必须填可登记的真实域名&#34;] C -->|&#34;否&#34;| D{&#34;带非默认端口吗&#34;} D -->|&#34;是&#34;| X3[&#34;拦下:合法域名只认域名本身&#34;] D -->|&#34;否&#34;| E{&#34;在合法域名清单里吗&#34;} E -->|&#34;否&#34;| X4[&#34;拦下:域名未登记&#34;] E -->|&#34;是&#34;| F[&#34;放行,请求真正发出去&#34;]

这张图要你注意它是逐层短路的:只有前面全过了,才会走到最后那个「在不在清单里」的判断。所以「我明明配了域名还报错」,多半是卡在前三层,压根没轮到比对登记簿。

七、几个特别容易踩的坑

把开发者工具的开关当成配置。 那个勾只是本机调试用的,关掉它不影响后台登记簿,也不影响真机。很多人在工具里跑通就以为联调结束,直到提测才被真机打回来。

拿本地地址硬上真机。 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 域名 生效 提测、体验版、上线前

八、出问题时,下一步往哪走

把前面的判断串成一条排查路径,遇到「点了没数据」照着往下走就行,不用每次重新想。

flowchart TD A[&#34;真机上点了没数据&#34;] --> B{&#34;curl 同一个地址能通吗&#34;} B -->|&#34;不能&#34;| C[&#34;先查后端与网络,别动白名单&#34;] B -->|&#34;能&#34;| D{&#34;工具能通,真机不通吗&#34;} D -->|&#34;是&#34;| E[&#34;多半是本机勾了不校验,真机会真校验&#34;] D -->|&#34;否&#34;| F{&#34;fail 里的 errMsg 说什么&#34;} F -->|&#34;域名未登记&#34;| G[&#34;去后台补 request 合法域名&#34;] F -->|&#34;握手失败&#34;| H[&#34;查证书链与服务端 TLS 版本&#34;] F -->|&#34;超时&#34;| I[&#34;回到后端和网络排查&#34;] G --> J{&#34;要改的是生产配置吗&#34;} H --> J J -->|&#34;否&#34;| K[&#34;本地或测试环境改完重新编译验证&#34;] J -->|&#34;是&#34;| L[&#34;写建议方案,交负责人人工确认&#34;] L --> M{&#34;审批通过且留有原配置吗&#34;} M -->|&#34;否&#34;| N[&#34;暂缓,补齐回滚点再评估&#34;] M -->|&#34;是&#34;| O[&#34;按方案执行并核对结果,异常就用回滚点恢复&#34;]

这张图要你注意最后那几道菱形。改生产环境的服务器域名属于会影响全部用户的操作,正确姿势是写出建议方案,说明影响面、目标值和回滚点,交给负责人人工确认、走完审批再执行,并且执行前真的留着能退回去的旧配置。别自己登录后台顺手就改,也别拿正式域名当调试开关来回试。

还有一条流程上的坑:为了查问题把预览报错截图、响应内容直接甩到群里,很容易把敏感信息带出去。手机号写成 138****5678,Token 只留前几位如 sk-1***,客户名称和地址一并隐去,再往外发。

九、想真正弄明白,按这个顺序练

第一步,把第四节那两个文件照着敲一遍,在开发者工具里把「不校验合法域名」勾上、去掉各跑一次,盯着 fail 里那句 errMsg 看清楚。两种结果一对照,「校验在哪一层」这件事就不用背了。第二步,把第六节的脚本存下来跑一遍,然后自己往 cases 里加地址,比如带个查询参数、换个大写主机名、写个 IPv6,猜一猜会卡在第几层,再拿输出对答案。第三步,找一台有正式域名和证书的测试环境,把整条正式链路走通,体会一下「配好了就再也不用管」是什么感觉。

工作里还有两条比记住规则更值钱。一条是联调时先给证据:把 url、errMsg、curl 的结果三联发过去,别只说一句「我这边连不上」,沟通成本立刻降下来。另一条是分清环境,本地怎么方便怎么来,提测和上线前必须按正式链路验一遍,别把调试开关的宽松当成线上的默认状态。慢慢你会发现,这类问题真正难的不是配置在哪儿填,而是先判断清楚它拦在哪一层;养成先看证据、再定哪一层、最后动手的习惯,比记住十条规则都管用。

十、最后总结

回到开头那个下午。让人耗掉半天的不是接口有多难,是一直在后端找一条根本没发出去的请求。小程序和浏览器最大的差别,在于 wx.request 发请求之前,微信客户端会先拿地址去比对那份 request 合法域名清单;校验在客户端完成,不通过就直接回调 fail,请求连出网的机会都没有,所以后端日志里空空如也,而开发者工具默认关掉了这道检查,真机预览却会认真执行,同一段代码才有了两个结果。

把顺序记住就够了:先用 curl 确认后端活着,再读 fail 里的 errMsg,然后按「协议、域名形式、端口、登记簿」这四层逐层对一遍,绝大多数「配了还报错」都停在前三层。改配置时记得合法域名是域名级而不是接口级,填一次主机名后面的路径都通用;证书链和 TLS 版本属于另一层的事,得找负责网关的同事,改 url 救不了。回去可以把那两个文件在工具里跑一遍、把校验脚本加上几个自己编的地址试试,再给自己负责的小程序画一张从点击到后端的链路图,下次再遇到「点了没数据」就能几分钟说清是哪一层的事。真要动生产环境的域名,写方案、请负责人确认、走完审批并留好回滚点,别自己直接改;往外发报错截图前把手机号和凭证打码。工具给你的是证据,判断靠的还是那句老话------先看清楚,再动手。

相关推荐
djxzyr5 小时前
微信小程序传感器实战:罗盘、加速计、陀螺仪与加速度实时波形
微信小程序·小程序
陈拉斯2 天前
无后端的人格测试小程序:当「数据不出设备」变成架构约束,我学到了什么
微信小程序
李纲明2 天前
微信小程序开了 Skyline 后样式全乱、滚动对不上甚至部分组件不能用?Skyline 怎么接才稳
javascript·微信小程序·小程序·devdiy
李纲明2 天前
微信小程序等位大桌被小桌占掉或过号回来就闹:先核桌型分队与过号容忍次数,再查门口屏与推送同源
微信小程序·devdiy·等位排队·桌型分队·过号重排·门口屏·推送同源
李纲明3 天前
微信小程序团课临开课才取消或空位没人补:先核取消时限与自动释放,再查候补确认与预扣回滚
微信小程序·devdiy·团课预约·取消时限·空位释放·候补确认·预扣回滚
用户034187671383 天前
用秒哒做了个拍照识餐小程序,上线两周踩的 4 个坑
微信小程序
李纲明3 天前
微信小程序租赁归还说本来就坏或配件对不上:先核借还点验与随单存证,再查差异计价公示
微信小程序·devdiy·租赁点验·借还拍照·随单存证·差异计价·押金释放
李纲明4 天前
微信小程序次卡跨店对不上账或前台随手改余次:先核流水只增不改与统一日切,再查冲正权限与总部只读
微信小程序·devdiy·核销流水·跨店次卡·日切对账·冲正权限·总部只读
李纲明4 天前
微信小程序维修拆机后口头加价或未确认就开工:先核验机快照与报价确认,再查补充报价与取机核验
微信小程序·devdiy·维修验机·报价确认·报价快照·补充报价·取机核验