Skip to content

常见问题

遇到问题或建议请提 issue

Q:抓包列表中为何显示 Tunnel to

通常出现该提示源于以下几种情况。请根据您的具体场景参照对应的解决方案:

  1. 普通的 TCP 连接(无法解析为 HTTP/HTTPS 请求)

  2. 未启用 HTTPS 抓包(最常见)

    • 原因:您未安装根证书或未开启 Enable HTTPS 选项。因此,Whistle 无法解密 HTTPS 流量,只能将其显示为加密隧道。
    • 解决方案:请安装根证书并开启 Enable HTTPS 选项。
  3. 捕获错误(captureError

  4. 发往 IP 地址的请求

    • 原因:该请求使用了字面 IP 地址(例如 https://192.168.1.1)而非域名。对于此类请求,大多数客户端不会发送 SNI 信息,导致 Whistle 无法自动将其识别为 HTTPS 请求。
    • 解决方案:您需要显式配置规则来告知 Whistle 对该 IP 进行 HTTPS 捕获。详情请参见下方问答:Q:如何捕获发往 IP 地址的 HTTPS 请求?

Q:抓包列表中出现 captureError 的原因?

  1. 发出请求的客户端没有安装根证书,安装方法参考:
  2. ssl pinning 问题
    • 对该域名的 HTTPS 请求不解密:域名 disable://capture 或只针对指定客户端的请求 域名 disable://capture includeFilter://reqH.user-agent=/xiaomi/i
    • 使用可以规避 ssl pinning 的系统或模拟器运行客户端
    • 寻找其它规避措施 https://blog.csdn.net/chiehfeng/article/details/134033846
  3. 系统信任的根证书默认对 Firefox 无效,需要单独为 Firefox 配置证书

方案1:为 Firefox 单独安装证书

在 Firefox 设置中:

  • 进入 选项 > 隐私与安全 > 证书
  • 点击 "查看证书" → "证书机构"
  • 导入下载的 .cer 文件
  • 勾选 "信任此CA" 所有选项

方案2:强制 Firefox 使用系统证书(推荐)

  • 搜索首选项:security.enterprise_roots.enabled
  • 将值改为 true
  • 重启浏览器生效

Q:为何安装了根证书并开启了 Enable HTTPS,对 IP 地址的 HTTPS 请求仍无法解密?

这是因为对于直接使用 IP 地址发起的 HTTPS 请求,客户端通常在握手阶段不会发送 SNI 信息。缺少 SNI 使得 Whistle 无法快速判断这是一个需要解密的 HTTPS 请求,且大部分这类请求都是普通 TCP 请求,从而可能将其视为普通的 TCP 流量处理。可以通过配置规则,显式地告知Whistle将特定IP的请求识别为HTTPS并进行解密捕获:

txt
ip[:port] enable://captureIp

# 或
ip[:port] enable://capture

Q:如何配置双向认证(mTLS)的 HTTPS 请求?

客户端证书设置参考:@clientCert://

Q:如何查看 Whistle 运行过程中的日志?

  1. 界面 Network > Tools > Server 查看错误日志
  2. 导致进程 Crash 的异常日志文件:~/.WhistleAppData/whistle.log

Q:如何同时启多个 Whistle 实例?

多实例运行时需满足:

  • 每个实例使用独立目录
  • 配置不同监听端口
sh
w2 start
2 start -p 8100 -S storageName2

Q:普通请求如何不通过代理直接访问 Whistle 不被当成内部请求?

Whistle 默认会将所有发往代理端口(如 127.0.0.1:8899)的请求视为内部管理请求,可以使用 /-/ 路径前缀绕过内部请求识别,如:

  1. http://127.0.0.1:8899/-/xxx:Whistle 自动转成普通请求 http://127.0.0.1:8899/xxx
  2. 通过配置规则将该请求转发到目标 URL:
    txt
    http://127.0.0.1:8899/xxx https://www.test.com/xxx

Q:Rules 如何支持多选?

在 Rules 界面中打开 Settings 对话框,勾选 Use multiple rules 即可

Q:如何根据请求内容匹配规则?

利用过滤器:

Q:iOS 安装完根证书还是无法打开 HTTPS 页面的可能原因?

检查是否完成"完全信任"设置:设置 → 通用 → 关于本机 → 证书信任设置

Q:Android 安装完根证书还是无法打开 HTTPS 页面的可能原因?

  1. ssl pinning 问题
    • 对该域名的 HTTPS 请求不解密:域名 disable://capture 或只针对指定客户端的请求 域名 disable://capture includeFilter://reqH.user-agent=/xiaomi/i
    • 使用可以规避 ssl pinning 的系统或模拟器运行客户端
    • 寻找其它规避措施 https://blog.csdn.net/chiehfeng/article/details/134033846
  2. 如果是自己公司的 APP,可以参考Android 开发文档 开启信任用户自定义根证书

Q:如何对 Whistle 转发的请求设置用户名和密码?

  1. Whistle 内部请求认证:w2 start -n 用户名 -w 密码 或自己开发插件,防止未授权操作规则和配置
  2. 代理请求的权限控制:需要借助插件 whistle.proxyauth 或自己开发插件

Q:如何添加自定义证书?

进入证书管理页面

  1. 点击顶部菜单栏 HTTPS > View Custom Certs > Upload
  2. 上传证书文件
    • 证书文件:必须使用 .crt 后缀
    • 私钥文件:必须使用 .key 后缀

    文件名要求:

    普通域名证书

    example.com.crtexample.com.key

    根证书(必须严格命名)

    root.crtroot.key

Q:版本更新问题

客户端版本只需重新下载最新版本并安装即可:https://github.com/avwo/whistle-client

命令行版本更新:

sh
npm i -g whistle && w2 restart

遇到安装慢或安装失败的问题可以尝试改镜像:npm i -g whistle --registry=https://registry.npmmirror.com && w2 restart

遇到权限问题可以加 sudo

sh
sudo npm i -g whistle
w2 restart

重启后命令行显示的 Whistle 版本与当前安装版本不符,可能是 Node.js 版本更新导致 PATH 路径变更。

解决方法:

  1. 确认版本是否有问题:
    sh
    w2 -V
  2. 找命令路径(所有系统通用)
    sh
    which w2  # Linux/Mac
    where w2  # Windows
  3. 清理冲突
    sh
    # 删除旧版本(根据上一步找到的路径)
    rm -f /usr/local/bin/w2  # 示例路径
    
    # Windows示例(需管理员权限)
    del "C:\Program Files\nodejs\w2.cmd"
  4. 恢复运行,操作完成后执行 w2 -V 查看版本是否更新:
    • 如果输出的版本还有问题重复上述操作
    • 如果命令 w2 找不到,请手动配置 PATH

Q:如何过滤抓包界面中的频繁轮询请求?

频繁的轮询请求(如心跳检测、状态上报)会刷屏并干扰主要请求的分析。您可以通过以下步骤快速隐藏它们:

在抓包列表中找到任意一个轮询请求,右键菜单选择合适的过滤规则:

  • Settings / Exclude All Matching Hosts:隐藏所有来自对应域名的请求(只对当前浏览器生效)
  • Settings / Exclude All Matching URLs:隐藏与当前 URL 匹配的所有请求(不包含请求参数,且只对当前浏览器生效)

Q:如何修改 Whistle 文档?

Whistle 文档源文件地址:https://github.com/avwo/whistle/tree/master/docs

本地启动文档服务:

sh
npm run docs:dev

Q:如何反馈问题?

New issue:https://github.com/avwo/whistle/issues