前端码农

Appearance

Whistle 使用指南 ​

Whistle 是基于 Node.js 实现的跨平台抓包调试代理工具，通过将设备流量指向本地代理端口，实现请求拦截、修改、重定向、Mock、注入等能力。本篇从「代理拦截原理」出发，梳理从环境搭建、HTTPS 证书、多端代理到高级调试的完整链路，帮助你构建对代理调试工具的系统认知。

导航目录 ​

一、环境搭建篇 ​

二、代理与证书篇 ​

三、高级调试篇 ​

四、实践与排障篇 ​

安装 Whistle ​

核心原理：Whistle 如何拦截流量

Whistle 本质是一个运行在本地（默认 8899 端口）的 HTTP/HTTPS 代理服务器。当把浏览器或手机的网络代理指向它后，所有请求都会先经过 Whistle，命中规则的请求被拦截并按规则处理（重定向/Mock/延迟/注入等），未命中的则原样转发到真实服务器。

text
                          ┌─(命中规则)─► 拦截处理（重定向/Mock/注入/延迟）─┐
浏览器/手机 ─(请求)─► Whistle 代理:8899                                    ├─► 返回响应给浏览器/手机
                          └─(未命中)──► 真实服务器 ─────────────────────────┘
bash
npm install -g whistle

常用命令 ​

bash
w2 start     # 启动 Whistle（开机后需要在 CMD 中输入）
w2 restart   # 重启 Whistle
w2 stop      # 停止 Whistle
w2 run       # 调试模式启动（用于查看异常及插件开发）

浏览器代理配置 ​

代理插件的作用

浏览器默认走系统代理，全局切换较繁琐。使用 ZeroOmega 等代理管理插件，可为浏览器单独设置代理并一键开关，避免影响系统其他应用，是前端调试的推荐方式。

1. 安装代理插件 ​

  • ZeroOmega 下载

  • 推荐插件：Zeroomega-3.4.1.crx

  • 注意：Proxy SwitchyOmega 已不被新版谷歌支持

2. 配置代理设置 ​

浏览器代理配置

安装 HTTPS 证书 ​

为什么必须安装证书？

HTTPS 流量是加密的，代理默认无法查看内容。Whistle 采用 中间人（MITM） 机制：它用自签根证书为目标域名动态签发证书，冒充服务器与客户端握手，从而解密流量。因此客户端必须信任 Whistle 的根证书，否则浏览器会报「证书不受信任」并拦截 HTTPS 请求。

text
客户端                    Whistle                    真实服务器
   |  1. HTTPS 请求          |                            |
   | ──────────────────────►|                            |
   |  2. 动态签发证书冒充服务器|                            |
   | ◄──────────────────────|                            |
   |                        |  3. 以客户端身份请求         |
   |                        | ──────────────────────────►|
   |                        |  4. 加密响应                |
   |                        | ◄──────────────────────────|
   |  5. 解密查看/修改再加密返回|                            |
   | ◄──────────────────────|                            |

步骤 ​

  1. 访问 http://127.0.0.1:8899/
  2. 选择 HTTPS → 勾选 "Capture TUNNEL CONNECTs" → 点击 "download"

下载HTTPS证书

Windows 系统 ​

受信任的根证书

  • 安装证书时需手动选择**"受信任的根证书"**目录

Mac 系统 ​

mac1mac2

  • 双击下载的 rootCA.crt
  • 在钥匙串访问中，将 whistle 证书设置为**"始终信任"**

配置 Host 代理规则 ​

操作步骤 ​

  1. 访问 http://127.0.0.1:8899/
  2. 选择左侧 "Rules" → 点击顶部 "Create"
  3. 输入规则名称创建代理规则

代理配置

环境配置 ​

本地 Whistle 代理通常包含以下环境：

  • local
  • dev
  • ...

可通过双击规则名快速切换环境

手机代理配置 ​

手机代理原理

手机代理与浏览器同理——把手机 WiFi 的代理指向电脑的 局域网 IP + Whistle 端口（8899），手机流量即可经电脑上的 Whistle 转发处理。关键前提是两台设备在同一局域网，且手机同样需要安装并信任 Whistle 证书才能抓取 HTTPS。

前提条件 ​

  • 手机与电脑需在同一局域网

代理设置 ​

查看 IP 地址 ​

  • 访问 http://127.0.0.1:8899/ 点击右上角 "Online"
  • 或在 CMD 中输入 ipconfig

iOS 系统 ​

ios

  • 点击 WiFi → 配置代理 → 手动 → 输入 IP 和端口

Android 系统 ​

安卓

  • 长按 WiFi → 修改网络 → 显示高级选项 → 配置代理

安装手机证书 ​

下载证书 ​

二维码

  • 扫描二维码下载证书

Android 安装 ​

  • 打开下载的文件 → 输入锁屏密码
  • 证书名称随意，必须勾选"VPN 和应用"

iOS 安装 ​

  1. Safari 访问 rootca.pro 或扫描二维码安装

  2. 设置 → 通用 → 描述文件 → 安装证书

安装证书

  1. 设置 → 通用 → 关于本机 → 证书信任设置 → 信任该证书

信任证书

功能使用 ​

规则语法速查

Whistle 规则统一采用 匹配模式 操作协议://参数 的格式。常用操作协议：redirect://(重定向)、statusCode://(改状态码)、resDelay://(延迟)、resBody://(替换响应体 Mock)、htmlAppend://(注入脚本)、weinre://(远程调试)。左侧匹配可用域名、路径或正则。

页面重定向 ​

功能说明：将一个 URL 重定向到另一个 URL，用于测试不同环境或页面。

bash
https://www.test1.com/ redirect://https://www.test2.com/
  • 访问 www.test1.com 时自动跳转到 www.test2.com

模拟网络问题 ​

模拟接口错误 ​

功能说明：模拟接口返回错误状态码，用于测试错误处理逻辑。

bash
wq.xx.com/official_account/queryCouponInfo statusCode://500
  • 接口返回 500 状态码

模拟网络延迟 ​

功能说明：模拟网络延迟，用于测试应用在慢速网络下的表现。

bash
wq.xx.com/official_account/queryCouponInfo resDelay://1000
  • 接口延迟 1 秒响应

Mock 接口数据 ​

功能说明：使用本地 JSON 文件模拟接口返回数据，用于前端开发和测试。

bash
https://beta-api.m.xx.com/queryCouponInf resBody://{queryCouponInf.json}

mock

  • 接口返回本地 JSON 文件内容

Mock 的典型场景

resBody:// 是前后端并行开发的利器：后端接口未就绪时，前端可用本地 JSON 先行联调；也可用于复现线上异常数据、构造边界值测试。配合 values 面板管理 Mock 数据，比手改代码更灵活且不侵入项目。

注入 Eruda 调试工具 ​

功能说明：在页面中注入 Eruda 调试工具，方便在移动端或生产环境进行调试。

配置规则 ​

  • 通过 Ctrl+单击模拟数据名称（html_test）跳转到 values 界面，写 js 代码
bash
https://m.xx.com/ htmlAppend://{html_test}

注入1

编写注入代码 ​

注入2

html
<script src="https://cdn.bootcss.com/eruda/1.5.4/eruda.min.js"></script>
<script>
  eruda.init();
  window.GLOBAL_SQ_HEADER = true;
</script>

注意：域名需精确匹配，避免影响其他接口

配置 Weinre 远程调试 ​

功能说明：使用 Weinre 进行远程调试，查看移动端页面的 DOM 结构、网络请求等。

配置规则 ​

bash
https://m.xx.com/ weinre://test1

使用步骤 ​

  1. 保存规则后，鼠标悬停 weinre 展开菜单
  2. 点击新建的 test1 css

调试界面 ​

weinre界面

Eruda 与 Weinre 如何选择

  • Eruda：注入到页面内的移动端控制台，查看 Console/Network/Element 等，在手机上直接操作，轻量、零配置，适合快速排查。
  • Weinre：远程调试，在电脑上审查手机页面的 DOM 与样式，适合处理复杂布局问题，但功能较老、不支持断点。
  • 现代方案更推荐 Chrome DevTools 远程调试（chrome://inspect），Weinre 主要用于无法直连 USB 的场景。

最佳实践 ​

  1. 规则管理：按照环境和功能对规则进行分类，便于管理和维护
  2. 证书安装：确保所有设备都正确安装了 HTTPS 证书，避免 HTTPS 拦截失败
  3. 域名匹配：使用精确的域名匹配规则，避免影响其他接口
  4. 规则备份：定期备份 Whistle 规则，防止规则丢失
  5. 性能优化：避免创建过多规则，影响 Whistle 的运行性能

常见问题 ​

1. 启动失败 ​

  • 检查端口是否被占用：netstat -ano | findstr :8899
  • 尝试使用其他端口启动：w2 start --port 8888

2. HTTPS 拦截失败 ​

  • 确保已正确安装并信任 HTTPS 证书
  • 检查浏览器是否允许不安全的证书

3. 手机代理无法连接 ​

  • 确认手机和电脑在同一局域网
  • 检查防火墙是否阻止了连接
  • 验证 IP 地址和端口是否正确

结语：抓住「代理 + 证书」两个核心

Whistle 的所有能力都建立在两个基础之上——代理让流量流经本地（决定了「能不能拦」），证书信任让 HTTPS 可解密（决定了「能不能看内容」）。理解这两点，无论是排查连不上、抓不到 HTTPS，还是设计复杂的重定向/Mock/注入规则，都能快速定位问题根源。剩下的只是规则语法的熟练度问题。