Whistle 抓包调试工具：从原理到实战全指南

前言

在前端开发和移动端调试中，我们经常需要拦截、查看甚至修改 HTTP/HTTPS 请求。Whistle 是一款基于 Node.js 的跨平台网络调试工具，它功能强大、配置灵活，既能代理电脑本地的请求，也能代理手机端的流量，是前端工程师的必备利器。

本文将从 网络原理 出发，深入讲解 Whistle 的核心机制，并通过实战示例帮助你快速上手。

一、Whistle 是什么？

Whistle 是一个基于 Node.js 实现的 HTTP/HTTPS 抓包代理调试工具，类似于 Charles、Fiddler，但它完全开源、跨平台，且通过类似 hosts 的规则语法来配置转发与 Mock，使用门槛更低。

核心能力包括：

• 🔎 抓包：查看所有经过代理的 HTTP/HTTPS 请求与响应
• 🔀 转发：将请求从一个地址转发到另一个地址（如本地开发服务器）
• 🛠️ Mock：拦截请求并返回自定义的响应数据
• ✏️ 修改：注入自定义 JS/CSS、修改请求头/响应头等
• 📱 移动端调试：代理手机流量，调试 App 内的 H5 页面

二、核心原理：代理是怎么工作的？

理解 Whistle 的关键在于理解 正向代理（Forward Proxy） 的工作机制。

2.1 正向代理流程

1
2
3
4
5
6
7
8
9
10
11

sequenceDiagram
    participant Client as 客户端(浏览器/App)
    participant Whistle as Whistle 代理服务器
    participant Server as 目标服务器

    Client->>Whistle: 1. 发送 HTTP 请求
    Note over Whistle: 2. 根据规则匹配<br>决定转发/Mock/修改
    Whistle->>Server: 3. 转发请求到目标服务器
    Server->>Whistle: 4. 返回响应
    Note over Whistle: 5. 可修改响应内容
    Whistle->>Client: 6. 返回响应给客户端

当你配置系统代理或手机 Wi-Fi 代理指向 Whistle 后，所有 HTTP 流量都会先经过 Whistle，再由 Whistle 转发到真实服务器。这就给了我们”中间人”的能力——查看、修改、甚至替换请求和响应。

2.2 HTTPS 抓包：中间人攻击（MITM）

HTTPS 使用 TLS 加密通信，正常情况下代理无法查看加密内容。Whistle 通过 MITM（Man-in-the-Middle） 方式解决这个问题：

1. Whistle 生成一个自签名的 根证书（Root CA）
2. 客户端信任该根证书（需要手动安装）
3. 当客户端发起 HTTPS 请求时，Whistle 动态签发一个目标域名的证书
4. 客户端与 Whistle 建立 TLS 连接（用 Whistle 签发的证书）
5. Whistle 与真实服务器建立另一条 TLS 连接
6. Whistle 在中间解密、查看/修改后，再加密转发

三、安装与启动

3.1 安装

确保你已安装 Node.js（建议 v12+），然后全局安装 Whistle：

1

npm install -g whistle

3.2 启动

1

w2 start

启动成功后，Whistle 默认监听 8899 端口。打开浏览器访问：

1

http://127.0.0.1:8899

即可看到 Whistle 的管理界面。

3.3 常用命令

四、配置代理

4.1 电脑端代理配置

方式一：系统代理（全局）

• macOS：系统偏好设置 → 网络 → 高级 → 代理 → Web 代理 / 安全 Web 代理 → 设置为 127.0.0.1:8899
• Windows：设置 → 网络和 Internet → 代理 → 手动设置代理 → 地址 127.0.0.1，端口 8899

方式二：浏览器插件（推荐）

使用 SwitchyOmega（Chrome 插件）可以更灵活地管理代理：

1. 安装 SwitchyOmega
2. 新建情景模式，代理协议选 HTTP，服务器 127.0.0.1，端口 8899
3. 需要调试时切换到该情景模式，不需要时切回”直接连接”

4.2 手机端代理配置

手机端代理的前提：手机和电脑在同一个局域网内。

1. 查看电脑的局域网 IP（如 192.168.1.100）
2. 手机 Wi-Fi 设置 → 配置代理 → 手动
   • 服务器：192.168.1.100
   • 端口：8899
3. 手机浏览器访问 http://192.168.1.100:8899 确认连接成功

4.3 安装 HTTPS 证书

如果需要抓取 HTTPS 请求，必须安装并信任 Whistle 的根证书：

1. 浏览器打开 http://127.0.0.1:8899（或手机端用电脑 IP）
2. 点击顶部菜单 HTTPS → Download RootCA 下载证书
3. macOS：双击安装 → 钥匙串访问中找到该证书 → 设置为”始终信任”
4. iOS：安装描述文件后，还需在 设置 → 通用 → 关于本机 → 证书信任设置 中启用
5. Android：设置 → 安全 → 安装证书（不同品牌路径略有差异）

五、规则配置详解

Whistle 的强大之处在于它的 规则系统。Whistle 支持两种规则书写形式：

形式一：匹配模式（Pattern → Target）

左边是匹配模式（域名、路径、正则等），右边是操作目标。这是最常用的形式，典型场景是将线上接口代理到本地开发服务器：

1

匹配模式 操作协议://操作值

示例：

1
2
3
4
5

# 将线上 API 代理到本地
api.example.com http://127.0.0.1:3000

# Mock 数据
api.example.com/api/user resBody://{mock-data}

形式二：IP 映射模式（IP → Domain）

左边是真实的 IP 地址，右边是域名。这种写法和操作系统的 hosts 文件 格式完全一致，用于将域名解析到指定 IP：

1

IP地址 域名

示例：

1
2
3
4
5

# 将 api.example.com 解析到本机
127.0.0.1 api.example.com

# 将多个域名指向同一个 IP
192.168.1.100 api.example.com cdn.example.com

5.1 请求转发

将线上接口转发到本地开发服务器：

1
2

# 将 api.example.com 的请求转发到本地 3000 端口
api.example.com http://127.0.0.1:3000

精确路径转发：

1
2

# 只转发特定路径
api.example.com/api/v1/user http://127.0.0.1:3000/api/v1/user

5.2 Mock 数据（返回本地 JSON）

使用 file:// 协议返回本地文件作为响应：

1

api.example.com/api/v1/user/info file:///Users/yourname/mock/user-info.json

也可以直接在 Whistle 的 Values 面板中定义 Mock 数据：

1

api.example.com/api/v1/user/info resBody://{mock-user}

然后在 Values 面板中创建名为 mock-user 的值：

1
2
3
4
5
6
7
8

{
  "code": 0,
  "data": {
    "name": "Test User",
    "age": 25
  },
  "message": "success"
}

5.3 修改请求头 / 响应头

1
2
3
4
5

# 添加/修改请求头
api.example.com reqHeaders://{custom-headers}

# 添加/修改响应头（如解决跨域）
api.example.com resHeaders://{cors-headers}

在 Values 中定义 cors-headers：

1
2
3

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization

5.4 注入 JS / CSS

1
2
3
4
5

# 注入自定义 JS
example.com jsPrepend://{debug-script}

# 注入自定义 CSS
example.com cssPrepend://{debug-style}

在 Values 中定义 debug-script：

1
2

console.log('Whistle injected script loaded!');
window.__DEBUG__ = true;

5.5 使用通配符和正则

1
2
3
4
5

# 通配符
*.example.com http://127.0.0.1:3000

# 正则匹配
/\/api\/v[0-9]+\/user/ http://127.0.0.1:3000

5.6 常用操作协议速查

六、实战场景

场景 1：联调时后端接口未就绪，Mock 接口数据

1
2

# Rules
api.example.com/api/v1/order/list resBody://{order-list-mock}

Values → order-list-mock：

1
2
3
4
5
6
7
8
9
10

{
  "code": 0,
  "data": {
    "list": [
      { "id": 1, "name": "订单A", "status": "pending" },
      { "id": 2, "name": "订单B", "status": "completed" }
    ],
    "total": 2
  }
}

场景 2：线上页面调试，将资源指向本地

1
2

# 将线上页面的 JS 文件指向本地构建产物
cdn.example.com/static/js/app.js file:///Users/yourname/project/dist/app.js

场景 3：手机端 H5 调试

1. 手机配置代理指向电脑 IP
2. 安装 HTTPS 证书
3. 使用 log:// 协议将页面的 console.log 输出到 Whistle 面板：

1

m.example.com log://

1. 在 Whistle 管理界面的 Network 面板中查看请求，Log 面板查看日志输出

场景 4：模拟弱网 / 慢速响应

1
2
3
4
5

# 延迟 3 秒返回
api.example.com/api/v1/data resDelay://3000

# 限制下载速度为 50KB/s
api.example.com/api/v1/data resSpeed://50

七、涉及的网络知识点

使用 Whistle 的过程中，以下网络知识会帮助你更好地理解它的工作原理：

7.1 HTTP 协议基础

• 请求方法：GET、POST、PUT、DELETE 等
• 请求头 / 响应头：Host、Content-Type、Authorization、Cookie 等
• 状态码：200、301、304、400、401、403、404、500 等

7.2 HTTPS 与 TLS

• TLS 握手过程：客户端与服务器协商密钥的过程
• 证书链：根证书 → 中间证书 → 服务器证书
• 为什么需要安装 Whistle 证书：让客户端信任 Whistle 签发的”假”证书

7.3 代理与网络层级

• 正向代理 vs 反向代理：Whistle 是正向代理，Nginx 常作反向代理
• 系统代理：操作系统级别的代理设置，影响所有应用
• PAC（Proxy Auto-Configuration）：通过脚本自动决定是否使用代理

7.4 DNS 与 Host

• DNS 解析：域名 → IP 地址的过程
• Host 文件：本地 DNS 覆盖，Whistle 的 host:// 规则本质上做的就是类似的事

7.5 跨域（CORS）

• 同源策略：浏览器安全策略，限制跨域请求
• CORS 头：通过 Whistle 注入 CORS 响应头，可以在开发阶段绕过跨域限制

八、Whistle 插件生态

Whistle 支持插件扩展，常用插件包括：

• whistle.inspect：类似 Chrome DevTools 的远程调试面板
• whistle.vase：更强大的 Mock 模板引擎
• whistle.script：用 JS 脚本编写复杂的请求/响应处理逻辑

安装插件：

1

npm install -g whistle.inspect

安装完成后在 Whistle 管理界面的 Plugins 面板中即可看到。

九、与其他工具的对比

十、最佳实践与注意事项

• ✅ 使用浏览器插件管理代理，避免全局代理干扰日常上网
• ✅ 合理组织规则分组，Whistle 支持多个 Rules 分组，可按项目分类
• ✅ 调试完毕后关闭代理，尤其是手机端，否则断开电脑后手机无法上网
• ✅ 及时清理不用的 HTTPS 根证书，减少安全隐患
• ✅ 善用 Network 面板的过滤功能，快速定位目标请求
• ⛔ 不要在生产环境使用 Whistle 做流量代理
• ⛔ 不要将 Whistle 的证书部署到用户设备上

总结

Whistle 是一个功能全面且灵活的网络调试工具。它基于 正向代理 + MITM 原理，让开发者能够轻松地抓包、转发、Mock 和修改请求。无论是本地开发联调、线上问题排查，还是移动端 H5 调试，Whistle 都是一个值得掌握的工具。

掌握 Whistle 的过程，也是加深对 HTTP/HTTPS 协议、代理机制、TLS 证书体系 等网络基础知识理解的过程。

License

本文采用 署名-非商业性使用-相同方式共享 4.0 国际 许可协议，转载请注明出处。

Share