whistle 支持通过 域名、路径、正则、通配符 等方式匹配请求URL外，也支持通过 filter 实现通过 请求方法、请求头、请求内容、响应状态码、响应头 等方式实现更复杂的匹配，如：

* reqHeaders://`x-test=${reqCookies.test}` includeFilter://reqH:cookies=/test=\d+;/

上述表示匹配请求头cookie里面包含 test=数字 的请求，且将cookie里面的 test 字段值设置到请求头里面。

除了上面的 excludeFilter 和 includeFilter 是通过 url、请求方法、请求头、请求内容、响应状态码、响应头 等过滤当前匹配的规则，whistle 也支持通过 ignore 忽略指定规则协议，如：

# 忽略 ke.qq.com 的所有 whistle 规则
ke.qq.com ignore://*

# 忽略 fudao.qq.com 的 host 规则
fudao.qq.com ignore://host

# 只保留 abcmouse.qq.com/path/to 的修改请求头规则
abcmouse.qq.com ignore://*
abcmouse.qq.com/path/to reqHeaders://x-test=abc ignore://-reqHeaders

更多内容参考：

1. pattern: https://wproxy.org/whistle/pattern.html
2. filter: https://wproxy.org/whistle/rules/filter.html
3. ignore: https://wproxy.org/whistle/rules/ignore.html
4. 如需跟灵活的匹配可以用插件：https://wproxy.org/whistle/plugins.html

查看 console 日志

1. log: https://wproxy.org/whistle/webui/log.html
2. vConsole 或 eruda: https://github.com/whistle-plugins/whistle.inspect

查看页面DOM结构

1. weinre: https://wproxy.org/whistle/webui/weinre.html
2. vConsole 或 eruda: https://github.com/whistle-plugins/whistle.inspect

1. ip访问，假设whistle所在的服务器IP为10.11.12.1，端口为 8899，则可以通过 http://10.11.12.1:8899/whistle.xxx/path/to 访问插件的 uiServer，如果本地可以直接通过 http://127.0.0.1:8899/whistle.xxx/path/to 访问
2. 配置代理后，可以通过 http:/local.whistlejs.com/whistle.xxx/path/to 访问
3. 用任意域名访问（需要配置代理或通过某种方式把该请求转到whistle）可以通过 https://ke.qq.com/...whistle-path.5b6af7b9884e1165...///whistle.xxx/path/to 访问，其中 ke.qq.com 可以替换成任意页面的域名

上述请求到插件到请求路径会自动变成 /path/to。

请求经过 Whistle 后，Whistle 会先做如下判断：

1. 是不是内置的管理界面域名（local.whistlejs.com, local.wproxy.org, l.wproxy.org, l.wisl.pro）
2. 是不是通过启动参数添加的管理界面域名 w2 start -l “d1,d2,d3”
3. 是不是通过 os.networkInterface() 获取的本机 IP（这种情况要求端口也一致）

只要满足其中一个条件就认为是请求管理界面的，否则为正常请求。
PS: 如果想让上述管理界面域名的请求也当作普通请求，可以在路径前面加 -，如：http://local.whistlejs.com/-/path/to

whistle 支持在启动参数的 shadowRules、界面的 Rules、以及插件的 rules.txt（每个rules.txt最多设置一个远程规则） 通过 @path 的方式动态嵌入规则：

1. path可以为 url、本地文件路径、插件的uiServer路径：如：@https://www.test.com/test、@E:\xxx\test.txt、@whistle.test/path/to
2. 如果关联路径的内容有变化，whistle会定时自动更新

如：

whistle 界面的 TextView 会强制将请求或响应内容转成文本类型，如果是非文本或非UTF8、GB2312编码的内容则可能出现乱码，可以查看二进制 HexView ，或通过插件对请求内容进行解析及还原：https://github.com/whistle-plugins/examples/tree/master/whistle.test-pipe

有些公司到内网访问外部网站需要通过代理转发，可以在whistle配置规则实现：

# http代理
* proxy://host:port

# https代理
* https-proxy://host:port

# socksv5代理
* socks://host:port

# pac脚本
* pac://http://pac.test.com/test.pac

可以把这些配置打包成一个插件，公司内部人员直接安装即可生效。

如果同时配置了hosts:

www.test.com/cgi-bin 10.10.1.2

请求会忽略代理规则，直接请求 10.10.1.2 ，可能出现请求无法访问。

whistle 也支持设置通过代理代理转发到指定ip到服务器：

www.test.com/cgi-bin 10.10.1.2 enable://proxyHost

这样如果同时配了 proxy，则请求会先经过proxy，并让proxy转发到指定到ip:port。

如果需要将某些请求转到指定ip:port的http server，可以采用下面的配置方式：

10.1.1.1:8080 enable://auto2http www.test.com www.qq.com

修改请求头：

# 修改请求头
pattern reqHeaders://value

# 修改响应头
pattern resHeaders://value

# 删除头字段
pattern delete://req.headers.cookie delete://res.headers.set-cookie

如：

www.test.com/index.html reqHeaders://x-test=123

value 也可以从Values或本地文件里面读取的json对象：https://wproxy.org/whistle/data.html

如果想灵活修改请求后响应头可以用headerReplace，用法参考：avwo/whistle#469

参考文档：

1. reqHeaders: https://wproxy.org/whistle/rules/reqHeaders.html
2. resHeaders: https://wproxy.org/whistle/rules/resHeaders.html
3. headerReplace: https://wproxy.org/whistle/rules/headerReplace.html
4. delete: https://wproxy.org/whistle/rules/delete.html

同时针对一些特殊头字段，whistle 还提供了更加方便的协议：

1. referer: https://wproxy.org/whistle/rules/referer.html
2. auth: https://wproxy.org/whistle/rules/auth.html
3. ua: https://wproxy.org/whistle/rules/ua.html
4. cache: https://wproxy.org/whistle/rules/cache.html
5. redirect: https://wproxy.org/whistle/rules/redirect.html
6. attachment: https://wproxy.org/whistle/rules/attachment.html
7. forwardedFor: https://wproxy.org/whistle/rules/forwardedFor.html
8. responseFor: https://wproxy.org/whistle/rules/responseFor.html
9. reqType: https://wproxy.org/whistle/rules/reqType.html
10. resType: https://wproxy.org/whistle/rules/resType.html
11. reqCharset: https://wproxy.org/whistle/rules/reqCharset.html
12. resCharset: https://wproxy.org/whistle/rules/resCharset.html
13. reqCookies: https://wproxy.org/whistle/rules/reqCookies.html
14. resCookies: https://wproxy.org/whistle/rules/resCookies.html
15. reqCors: https://wproxy.org/whistle/rules/reqCors.html
16. resCors: https://wproxy.org/whistle/rules/resCors.html

android 6.0 之后的一些app在成功安装证书后仍然无法对https连接进行手抓包，有可能是该app没有添加信任用户自定义证书的权限。请确认该app是否有如下配置：

<base-config cleartextTrafficPermitted="true">
  <trust-anchors>
    <certificates src="system" />
    <certificates src="user" />
  </trust-anchors>
</base-config>

ke.qq.com enable://abort reqDelay://6000

上述配置表示在等待6秒后把请求中断掉。

插件内置了临时存储和永久存储两种方式，这些数据都存储在内存或本地硬盘：

module.exports = (server, options) => {
  const { Storage, storage } = options;
  // new Storage(dir): （首字母大写）新建一个指定目录的存储对象
  // storage: （首字母小写）whistle 给插件提供的默认存储对象

  // 获取文件列表
  const fileList = storage.getFileList();

  // 存储 key-value
  storage.setProperty(key, value);

  // 获取key值
  const value = storage.getProperty(key);

  // 删除 key
  storage.removeProperty(key);

  // 大块数据保存到文件里面
  storage.writeFile(filename, content);

  // 读取文件
  const content = storage.readFile(filename);

  // 删除文件
  storage.removeFile(filename, content);

  // 判断文件是否存在
  storage.existsFile(filename);

  // 处理请求
  server.on('request', (req, res) => {
    // req.localStorage === storage;

    // sessionStorage 最多缓存12分钟
    const { sessionStorage } = req;

    // 设置key-value
    sessionStorage.set(key, value);
    
    // 获取key值
    const value = sessionStorage.get(key);

    // 删除key值
    sessionStorage.remove(key);

  });
};

当然whistle插件本身是一个node服务，你也可以自己实现存储到远程数据库等。

如果是请求出错，可以在 Network 里面的 Request 或 Response 的 Body 里面看到，有些请求会把异常作为响应内容直接输出到界面；如果是内部运行出现的非致命性异常，可以在 Network -> Log -> Server 里面看到；如果是导致程序crash的异常，日志信息会写在命令行启动的目录的 whistle.log 文件。

在本地替换或对线上响应内容强制 gzip，可以使用：

www.test.com/path/to file:///User/xxx/test enable://gzip

# 如果响应内容已经gzip，会自动忽略规则
ke.qq.com www.baidu.com enable://gzip

禁用 gzip 可以用：

ke.qq.com disable://gzip
# 或
ke.qq.com www.baidu.com disable://gzip

参考文档

1. file: https://wproxy.org/whistle/rules/rule/file.html
2. enable: https://wproxy.org/whistle/rules/enable.html
3. disable: https://wproxy.org/whistle/rules/disable.html

这种一般是镜像问题，可能该插件发布在私有的镜像，可以通过以下两种方式解决：

1. 设置 --registry，如 w2 i @org/whistle.xxx --registry=http://xxx.xnpm.com
2. 如果那边镜像有快捷的安装命令，如 tnpm、cnpm 等，可以用 w2 ti @org/whistle.xxx，即在 i 前面加快捷命令的前缀

参见：https://wproxy.org/whistle/webui/https.html

注意事项：

1. Windows: 注意第二步需要选择 Browser(浏览) > 受信任的根证书
2. Mac：安装后需要在证书列表搜索 whistle 并双击打开信任
3. iOS：需要在手机 设置 > 关于 > 证书信任 确认
4. Firefox：需要单独安装根证书

配置hosts：

pattern ip1:port ip2
pattern host://hostname1:port host://hostname2
www.qq.com/test host://ke.qq.com

www.test.com/path/to 127.0.0.1:6001

请求替换：

pattern http://ip1:port
pattern https://ip
www.qq.com/xxx http://www.test.com/path/to

www.test.com/path/to 127.0.0.1:6001/

前者不改变请求数据(url、头、内容)，只是将请求转发到知道到ip及port，后台收到的url不变；后者则会修改url及请求头host，后台收到的是新的url。

whistle 提供了四种搜索及过滤抓包数据的方法，方便大家快速精确获取想要的抓包数据，分别为：

1. 通过配置规则过滤抓包数据
2. 通过Network界面Filter菜单过滤抓包数据
3. 通过页面URL的hash参数过滤抓包数据
4. 通过Network界面下方搜索框搜索抓包数据

规则过滤

whistle支持通过 pattern enable://hide [filters] 方式隐藏抓包数据，如：

pattern 可以为域名、路径、通配符、正则等，详细内容参见：https://wproxy.org/whistle/pattern.html ，并可以结合 filter 可再根据请求方法、请求头、请求内容、响应状态码、响应头进行二次过滤。

ke.qq.com enable://hide
*.url.cn enable://hide excludeFilter:///^[^?]+\.js(\?|$)/i

上述配置效果如下，访问https://ke.qq.com，Network 上看不到 ke.qq.com 域的任何请求，*.url.cn 域名也只能看到后缀为 .js 的请求。

Network界面Filter菜单

Network界面上方 Filter 菜单可以配置界面过滤规则，界面从whistle获取的抓包数据先在此过滤后再决定是否显示到列表中。

Filter菜单里面包含 ExcludeFilter 和 IncludeFilter 两种过滤方式，支持通过关键字（不区分大小写）或正则表达式匹配URL(pattern)、请求方法（m:pattern）、客户端IP（i:pattern)、请求头内容（h:pattern)，请求头的host字段（H:pattern)，多个条件用空格或换行符隔开：

urlPatten
m:methodPattern
i:clientIpPattern
h:headersPattern
b:bodyPattern
H:reqHostPattern

如：

ExcludeFilter:

/\.js/i
h:x-test=hide
m:post

IncludeFilter:

.url.cn
hm.baidu.com
ke.qq.com

上述表示界面只显示URL包含 .url.cn、 或 hm.baidu.com、 或 ke.qq.com（不区分大小写），且URL不能包含 .js、 请求头里面不能有 x-test=hide（可以在cookie里面种这么一个值，则请求不会显示）、请求方法不能为 post。

Filter菜单配置的过滤规则是先将所有抓包数据请求到本地再进行过滤，且无法将过滤方式直接分享给他人，如果需要通过服务端过滤提升性能，可以用这么的请求参数过滤方式。

请求参数过滤

whistle 支持在抓包界面的URL设置过滤参数，后台会自动读取这些参数进行过滤，同样支持通过URL、客户端IP、请求头进行过滤：

http://local.whistlejs.com/#network?url=keyword&name=key0&value=keyword0&name1=key1&value=keyword1&...&name5=key5&value5=keyword5&ip=self,10.10.10.10

性能方面考虑，请求参数过滤方式不支持正则，只支持关键字不区分大小写

上述参数都是可选，其中 url 匹配请求URL，name, name1, ..., name5 共可设置6个key，对应6个关键字，可分别匹配请求头6个字段的值（这6个字段可选，必须按顺序设置，不能跳过其中一个，请求头的值是模糊匹配的，如果想变成精确匹配加个参数 &mtype=exact即可），ip为精确匹配对应的客户端IP（self关键字表示匹配本机IP）。

Network界面搜索框

上述几种过滤方法都是在抓包数据显示到Network之前做的过滤，主要用于精简Network的抓包数据，被过滤掉的数据无法再显示出来，除此之外，whistle提供了快速搜索方法，通过Network下方的搜索框可以根据URL、请求方法、客户端或服务端IP、响应状态码、请求头或响应头、请求内容或响应内容快速搜索想要的抓包数据。

其中：

1. pattern：可以为关键字或正则表达式(/regexp/i)，匹配请求URL
2. m:pattern：pattern可以为关键字或正则表达式(/regexp/i)，匹配请求方法
3. i:pattern：pattern可以为关键字或正则表达式(/regexp/i)，匹配客户端或服务端IP
4. s:code: code可以为关键字或正则表达式(/regexp/i)，匹配响应状态码
5. b:pattern：pattern可以为关键字或正则表达式(/regexp/i)，匹配请求或响应内容
6. h:pattern：pattern可以为关键字或正则表达式(/regexp/i)，匹配请求或响应头（包括key和value）

在访问本地或测试环境如果出现上述跨域问题，可以用 whistle 的 resCors 解决，有以下三种解决方式：

1. 通配符
2. 自动设置
3. 自定义

建议大家把 whistle 升级到 v2.5.3 及以上版本，否则前两种方式在处理 OPTIONS 请求会有问题。

有关 whistle 参见 Github：https://github.com/avwo/whistle

通配符

一般用于无需登录态的跨域请求，或者 crossorigin 属性设置为空或 anonymous 的 script 标签（如： <script crossorigin src="..."></script>，一般都设置为默认值 anonymous），可配如下规则解决：

pattern resCors://*

pattern 可以为域名、路径、通配符、正则等，详细内容参见：https://wproxy.org/whistle/pattern.html

例如（用 whistle 的 Composer 模拟请求）：

www.qq.com/test resCors://*

自动设置

一般用于需要登录且无人为特别限制的跨域请求，或者 crossorigin 属性设置为 use-credentials 的 script 标签（如： <script crossorigin="use-credentials " src="..."></script>），可配如下规则解决：

pattern resCors://enable # 或 pattern resCors://use-credentials

pattern 可以为域名、路径、通配符、正则等，详细内容参见：https://wproxy.org/whistle/pattern.html

例如（用 whistle 的 Composer 模拟请求)：

www.qq.com/test resCors://enable

自定义

自定义方式可以完全根据自己的需要设置响应的 cors 头，一般用于对请求有特殊限制的情形，比如只允许某些请求方法或自定义请求头访问等等，具体配置方式如下：

pattern resCors://(origin=xx&mehods=POST&headers=x-test)

pattern 可以为域名、路径、通配符、正则等，详细内容参见：https://wproxy.org/whistle/pattern.html

例如（用 whistle 的 Composer 模拟请求)：

``` test-cors1
origin: *
methods: POST
headers: x-test
credentials: true
maxAge: 300000
```
www.qq.com/test resCors://{test-cors1}

一般如果是静态资源设置 resCors://* 即可，CGI请求的话可以设置 resCors://enable，如果是对请求响应的cors头有特殊要求再用自定义方式，更多内容参见帮助文档：https://wproxy.org/whistle/rules/resCors.html

iOS 安装根证书后需要手动信任自定义根证书，设置路径：Settings > General > About > Certificate Trust Testings

可以用lack实现：https://github.com/avwo/lack