Whistle 跨平台 Web 调试代理技术调研

Whistle 是阿里开源的跨平台 HTTP/HTTPS/WebSocket 调试代理，基于 Node.js，通过规则文件灵活控制抓包、Mock、转发、注入脚本等行为。是国内前端团队广泛使用的 免费开源 Charles 替代，尤其适合需要版本化规则、团队共享和 CI 集成的场景。

一、 基本信息

二、 技术定位与简介

Whistle 通过本地代理（默认 127.0.0.1:8899）拦截流量，Web UI 管理规则：

• host、proxy、redirect 转发。
• resBody、statusCode Mock 响应。
• reqHeaders、resHeaders 修改头。
• jsAppend、cssAppend 注入调试脚本。
• 插件生态（whistle.chii 远程调试等）。

规则可保存为文本纳入 Git，团队共享 reproducible 调试环境。

三、 快速上手安装说明

pnpm add -g whistle
w2 start
# Web UI: http://127.0.0.1:8899

系统/浏览器代理设为 127.0.0.1:8899，HTTPS 需安装 Whistle 根证书（UI 中 QR/链接下载）。

规则示例：

# 将 API 映射到本地 json
api.example.com/users file://{desktop}/mock/users.json

# 延迟响应
api.example.com resDelay://3000

# 修改响应状态
api.example.com/statusCode://500

四、 核心特性

• 规则语法简洁强大。
• Web UI 实时编辑规则与查看请求。
• 支持 WebSocket。
• 插件扩展（vConsole 注入、Weinre 替代等）。
• 跨平台 Node 运行。
• 多用户/多环境规则分组。

五、 适用场景

适合：开源免费抓包、团队规则 Git 管理、H5 注入 vConsole、接口 Mock、内网穿透联调。

不适合：不愿配置 Node 的非技术测试人员（Charles GUI 更友好）、企业强制商业支持场景。

六、 技术亮点

规则即代码；国内文档与案例丰富；插件生态活跃；与移动端、WebView 联调成熟。

七、 技术局限与边界

1. 需理解规则语法学习曲线。
2. UI 美观度弱于 Proxyman/Charles。
3. Certificate Pinning 同样无法绕过。
4. 依赖 Node 环境维护。
5. 英文国际文档较少。

八、 生态地图

九、 生态集成

规则文件入 Git；与 pnpm monorepo 脚本 w2 start 集成；导出抓包给 Postman。

十、 开发与工程化

{
  "scripts": {
    "proxy": "w2 start -p 8899"
  }
}

团队 rules/dev.txt 按环境拆分；PR 评审 Mock 规则变更。

十一、 性能与安全

根证书仅开发机；规则注入脚本勿含恶意代码；公共网络慎用透明代理；抓包含 Token 勿外传。

十二、 技术对比

十三、 最佳实践

1. 规则分环境文件管理。
2. Mock 响应与 OpenAPI 契约对齐。
3. 联调完关闭系统代理。
4. 用 resDelay 测加载与超时 UI。
5. 插件注入 vConsole 仅限测试包。
6. 文档化团队统一 Whistle 端口与证书安装。

十四、 学习与社区资源

• 官方文档：https://wproxy.org/whistle/
• GitHub：https://github.com/avwo/whistle
• 规则语法：https://wproxy.org/whistle/rules/

十五、 总结

Whistle 是 国内团队首选开源抓包方案，以规则驱动实现 Mock、注入与转发，适合工程化程度高的前端团队；追求 GUI 体验可选 Charles/Proxyman。