Whistle 网络代理工具完全指南

简介

Whistle 是一款基于 Node.js 的跨平台网络代理工具，通过「规则拦截 - 流量转发 - 内容篡改」实现全场景网络调试。相比传统工具（Charles、Fiddler），Whistle 具有以下优势：

免费开源，跨平台支持（Windows/Mac/Linux）
规则配置灵活，支持正则表达式和通配符
支持多设备代理（手机、平板、电脑）
强大的插件生态系统

快速开始

安装

确保已安装 Node.js（v14+），然后全局安装 Whistle：

npm install -g whistle

启动服务

# 启动服务（默认端口 8899）
w2 start

# 其他常用命令
w2 stop      # 停止服务
w2 restart   # 重启服务
w2 status    # 查看状态

启动后访问 http://127.0.0.1:8899 进入管理界面。

配置浏览器代理

方式一：使用 SwitchyOmega 插件（推荐）

安装 SwitchyOmega Chrome 插件
新建代理配置：
- 代理协议：HTTP
- 代理服务器：127.0.0.1
- 代理端口：8899
切换到该配置即可

方式二：系统代理设置

在系统网络设置中配置 HTTP/HTTPS 代理为 127.0.0.1:8899

HTTPS 抓包配置

抓取 HTTPS 请求需要安装证书：

w2 ca

按提示安装证书并信任即可。

核心功能

工作原理

Whistle 本质是一个 HTTP/HTTPS 代理服务器 + 规则引擎：

接收请求 - 客户端请求发送到 Whistle 代理
规则匹配 - 根据配置的规则匹配请求（域名、路径、协议等）
流量处理 - 执行转发、Mock、替换、拦截等操作
返回响应 - 处理后的响应返回给客户端

规则语法

基本格式：

匹配模式 操作://参数

支持通配符和正则表达式：

# 精确匹配
example.com/api/user file://mock.json

# 通配符匹配
*.example.com 127.0.0.1:3000
**/api/** file://./mock/

# 正则匹配
/^https?:\/\/.*\.example\.com/ 127.0.0.1:3000

实战场景

1. 接口 Mock

模拟后端接口返回，前后端并行开发。

场景： Mock 用户信息接口

创建 user-mock.json：

{
  "code": 200,
  "data": {
    "id": 1001,
    "name": "张三",
    "role": "admin"
  }
}

配置规则：

example.com/api/user file:///path/to/user-mock.json

2. 资源替换

替换线上资源为本地文件，快速验证修复。

场景： 调试线上 JS 文件

# 替换单个文件
example.com/static/app.js file:///Users/dev/project/app.js

# 替换整个目录
example.com/static file:///Users/dev/project/dist

3. 请求转发

将生产环境请求转发到本地开发服务器。

# 域名转发
example.com 127.0.0.1:3000

# 路径转发
example.com/api 127.0.0.1:8080

4. 跨域处理

添加 CORS 响应头解决跨域问题。

example.com/api resHeaders://{
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Methods": "GET,POST,PUT,DELETE",
  "Access-Control-Allow-Headers": "Content-Type,Authorization"
}

5. 请求/响应修改

修改请求头：

example.com/api reqHeaders://{
  "Authorization": "Bearer token123",
  "X-Custom-Header": "value"
}

修改请求体：

example.com/api/submit reqBody://{
  "status": "published",
  "title": "Modified by Whistle"
}

修改响应体：

example.com/api/list resBody://{
  "code": 200,
  "data": [],
  "message": "Empty list"
}

模拟不同登录状态。

# 添加 Cookie
example.com reqCookies://{
  "userId": "123",
  "token": "abc",
  "sessionId": "xyz"
}

# 删除 Cookie
example.com reqCookies://{
  "userId": "",
  "token": ""
}

7. 请求拦截

# 返回 404
*.png statusCode://404

# 返回空响应
example.com/api/track statusCode://204

8. 异常场景模拟

模拟延迟：

# 延迟 3 秒
example.com/api/slow reqDelay://3000

模拟错误：

# 返回 500 错误
example.com/api/error statusCode://500 resBody://{"error": "Server Error"}

模拟弱网：

# 限速 50KB/s，延迟 200ms
example.com throttle://50k/200ms

9. 环境切换

快速切换不同环境（开发/测试/生产）。

# 开发环境
api.example.com dev-api.example.com

# 测试环境
api.example.com test-api.example.com

# 本地环境
api.example.com 127.0.0.1:8080

10. 移动端调试

手机配置代理：

获取电脑 IP 地址（如 192.168.1.100）
手机连接同一 WiFi
配置手机代理：
- 服务器：192.168.1.100
- 端口：8899
手机浏览器访问 http://192.168.1.100:8899，扫码安装证书

高级技巧

规则分组

使用 Values 功能定义可复用的数据：

# 在 Values 中定义 mock-user
{
  "code": 200,
  "data": {"name": "Test User"}
}

# 在 Rules 中引用
example.com/api/user resBody://{mock-user}

条件规则

根据请求方法、状态码等条件匹配：

# 仅匹配 POST 请求
example.com/api method://POST file://mock.json

# 仅匹配响应码 404
example.com statusCode://404 resBody://{"error": "Not Found"}

插件扩展

Whistle 支持插件扩展功能：

# 安装插件
npm install -g whistle.inspect

# 启动时加载插件
w2 restart

常用插件：

whistle.inspect - 请求详情查看
whistle.script - 自定义脚本处理
whistle.vase - Mock 数据管理

对比其他工具

特性	Whistle	Charles	Fiddler
价格	免费	付费（$50）	免费
跨平台	✅	✅	❌ Windows
规则配置	简单灵活	复杂	中等
性能	高	中等	中等
插件生态	丰富	较少	较多
学习成本	低	高	中等

常见问题

Q: 为什么 HTTPS 请求抓不到？

A: 需要安装并信任 Whistle 证书，执行 w2 ca 安装。

Q: 手机无法连接代理？

A: 确保手机和电脑在同一局域网，检查防火墙设置。

Q: 规则不生效？

A: 检查规则顺序（从上到下匹配）、匹配模式是否正确、代理是否开启。

Q: 如何调试 WebSocket？

A: Whistle 原生支持 WebSocket 抓包，在 Network 面板查看。

总结

Whistle 是一款强大而灵活的网络调试工具，适用于：

前后端并行开发（接口 Mock）
线上问题快速验证（资源替换）
跨域问题调试（CORS 配置）
移动端网络调试（多设备支持）
异常场景测试（延迟、错误模拟）

通过合理使用 Whistle，可以大幅提升开发调试效率。