编程 Whistle 抓不到联调包:回环旁路、localhost 解析到 ::1、级联代理这三处默认值

2026-11-17 00:04:01

Whistle 联调抓不到包:按三层顺序定位,而不是反复重启

项目信息:Whistle 仓库、桌面客户端、文档。Whistle 是基于 Node.js 的跨平台抓包/代理调试工具。

基础操作先对齐:

npm i -g whistle      # 或 brew install whistle
w2 start              # 默认端口 8899
w2 ca                 # 安装根证书,HTTPS 抓包必需
w2 proxy              # 设置系统代理;w2 proxy 0 关闭

Web UI 在 http://127.0.0.1:8899,或 http://local.whistlejs.com(未设系统代理时后者不可用)。规则形态是 pattern operatorURI,一行一条;operatorURI 既可以是路径(请求地址替换),也可以是 whistle 协议,如 resBody://{key}、file://、proxy://、enable://captureIp、replaceStatus://200。

联调时「抓不到包 / 代理不生效」的排查顺序建议固定为三层:

  1. 客户端有没有真的把流量交给 8899;
  2. 规则目标地址解析到了哪个协议栈(IPv4 / IPv6);
  3. 上游/级联代理是否写在 Rules 里,而不是塞在启动参数中。

三层是依次收窄的:上一层不通,下一层的现象根本不会出现,先跳着改规则基本是白费。

第一层:客户端有没有把流量交给 8899

现象:本地页面发出的请求在 Whistle 里完全看不到记录,UI 空白,没有任何 CONNECT 或请求条目。

判据:浏览器和代理插件默认不代理回环地址。Chrome + SwitchyOmega 的默认旁路列表就包含 localhost、127.0.0.1,这些请求根本不会进 Whistle。issue avwo/whistle#266 的结论是把 SwitchyOmega 的 bypass 列表改成 <-loopback>,并删掉其他 localhost 相关项;该 issue 中有用户反馈对 Edge 无效。Charles 官方 FAQ 同样承认抓不到 localhost 流量,这是系统/浏览器默认行为,不是 Whistle 的问题。

<-loopback> 的含义是「反转」回环旁路——连回环地址也走代理。它只影响客户端一侧,不改变 Whistle 自身的记录逻辑。

操作:改完插件旁路后重启浏览器代理,再发一次请求,确认 Whistle 里出现记录,才进入第二层。

第二层:规则目标解析到哪个协议栈

现象:请求已被记录(第一层通),但报 Error: connect ECONNREFUSED 127.0.0.1:10087,或者一直 pending 后 504。

判据:本地前端服务的 localhost 可能解析到 ::1,而不是 127.0.0.1。issue avwo/whistle#1145 就是这个场景:规则 xxx.com localhost:10087 报 ECONNREFUSED 127.0.0.1:10087。维护者 avwo 给了四条解法:

  • 规则里直接写 IPv6 字面量:xxx.com [::1]:10087;
  • 前端服务启动时绑 127.0.0.1 而不是 localhost(推荐——localhost 是域名,指向哪个 IP 由系统 hosts 决定,未配置时行为不确定);
  • 系统 hosts 加 127.0.0.1 localhost;
  • 降 Node 版本(见 CHANGELOG v2.9.73)。

issue avwo/whistle#1118(英文)是同一根因:双栈网络下 localhost:30473 连不上,换成 [::1]:30473 后恢复;维护者指向 Node 的 dns.lookup 文档,并说明需要 Node >= 22.1.0 才能用 IPv6-first 选项。

反方向也存在。issue avwo/whistle#1030:127.0.0.1:3000 一直 pending 后 504,改成 http://localhost:3000 就通,最终判断是本地服务的监听/配置问题。所以两个方向都要查:规则目标解析错,或服务本身只听某一栈。

操作:先在 Whistle 里确认请求已被记录(第一层通),再看 CONNECT 阶段的报错文本——ECONNREFUSED 后面跟的是哪个 IP,就是线索。

另一个默认值相关:新版 Whistle 默认不解析「域名为 IP」的 HTTPS 请求,需要加 * enable://captureIp(avwo 在 #1145 下的原话)。

第三层:上游/级联代理写在 Rules 里,不是启动参数

现象:配了上游代理,Wireshark 里却看到包直接发往目标服务器。

判据:级联代理要用规则配置,启动参数不生效。issue avwo/whistle#1326 中用户执行 w2 start proxy 172.31.208.1:7123 -p 8888 想级联上游,抓包显示流量没走代理;社区回复(echopi)指出应在 Rules 里写:

* proxy://172.31.208.1:7123

按上游协议选 https-proxy:// 或 socks://。只让海外域名走上游就写白名单正则:

/^https?:\/\/(.*\.)?(google|youtube|github)\.com\// proxy://172.31.208.1:7123

注意命中本地 host 改写的请求不会再级联。这条是社区答复,官方 rule.md 里 proxy 协议确实存在,具体优先级建议自测(未实测)。

HTTPS 与 mock 的前置条件

w2 ca 装好根证书后才能解 HTTPS 明文;手机要装到「受信任凭据/用户」里,部分机型凭据用途选错不生效。HTTP/2 站点需在 UI 里勾 Enable HTTP/2,否则抓不到(社区说明,未实测具体版本)。

mock 的落点是 Values + resBody:在 Values 页建一个 key(如 mock1),Rules 写 /api/x resBody://{mock1}。也可以用 file:// 指向本地文件,模板变量在反引号里引用 url、method、port 等,replaceStatus://200 用来改状态码。改完必须保存——Values/Rules 左上角红点消失才算生效,不保存不生效,这一条在联调时最容易漏。

与站内 #8578 的区别

站内 #8578 的《WireMock 3.13 回放支付接口》讲的是 stub 匹配与录制回放,属于「拿到请求之后怎么造响应」;本篇讲的是抓包代理链路本身不通时的三层判据,属于「请求怎么进到代理里」。两者互补,排障时先确认链路,再谈回放。

推荐文章

程序员茄子在线接单