Master Web Debugging with Whistle: A Frontend Engineer’s Guide

Preface

Why do we need a proxy tool and how much can a flexible, easy‑to‑use proxy improve development efficiency? A handy proxy lets you switch environments instantly, modify data on the fly, and locate issues on specific devices without waiting for services to restart.

Whistle Introduction

Whistle (pronounced "whistle") is a cross‑platform web debugging proxy built on Node, similar to Fiddler on Windows. It can view and modify HTTP, HTTPS, and WebSocket requests/responses, and can act as an HTTP proxy server. Unlike Fiddler’s breakpoint approach, Whistle uses a configuration‑based system supporting domain, path, regex, wildcard, and other matching methods, and can be extended via Node modules.

Comparison with Charles

Most developers start with Charles or Fiddler, but Whistle offers several advantages:

Open‑source and free, unlike the paid Charles.

Easy installation via a global npm package, which is familiar to frontend developers.

Centralized, flexible configuration stored in files, making sharing and editing straightforward.

Programmable extensions: when built‑in features are insufficient, you can develop plugins using npm packages.

How to Use

Installation and Usage

Whistle is distributed as an npm package, so install it with a single command (use sudo on macOS/Linux if you are not root):

# Install
npm install -g whistle
# Start
w2 start
# Restart
w2 restart
# Stop
w2 stop

Accessing the Main Interface

Open the UI at http://localhost:8899/#network. If you change the default port, replace 8899 with the port you configured.

Configuring the Proxy

Configuration Information Proxy Server : 127.0.0.1 (change to the remote server IP if deployed elsewhere) Default Port : 8899 (use -p to specify another port; see w2 help for details)

Whistle does not set the system proxy automatically; you must configure the proxy manually for the applications that need it.

System Proxy

System‑wide proxy settings differ by OS; refer to the relevant documentation.

Browser Proxy (Chrome example)

Although Chrome can set a proxy directly, using the SwitchyOmega extension is recommended because it also manages proxy rules for services like Google.

Mobile Proxy

Both devices must be on the same Wi‑Fi network. Configure the Wi‑Fi proxy on the mobile device (iOS example) to point to the IP of the machine running Whistle.

HTTPS Certificate

If you need to inspect HTTPS traffic, you must install a custom root certificate. Download the root certificate, enable HTTPS capture, and install the certificate on each platform.

Installing the Root Certificate

If you still see security warnings after installing, it may be because a previous connection has cached the old certificate; restart Whistle with w2 restart after a short wait.

After downloading rootCA.crt, open it to start the installation wizard.

Windows

Double‑click the certificate file and follow the prompts, ensuring it is placed under “Trusted Root Certification Authorities”.

macOS

After installing the certificate, open the certificate manager, locate the entry containing “whistle”, and set its trust level to “Always Trust”.

Firefox

Navigate to Preferences → Advanced → Certificates → Authorities → Import, select the certificate, check all boxes, and confirm.

iOS

After setting the proxy, open Safari and visit rootca.pro to install the certificate, or scan the QR code shown in Whistle’s console. iOS 10.3+ requires manual trust under Settings → General → About → Certificate Trust Settings.

Android

Scan the QR code from Whistle’s console or open rootca.pro in a browser to install.

Some browsers need manual installation via Chrome.

From Android 6.0 onward, apps must request the android.permission.INTERNET and android.permission.ACCESS_NETWORK_STATE permissions to trust user‑installed certificates.

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

Enabling HTTPS Interception

In Whistle’s UI, check the “Capture HTTPS CONNECTs” option; the feature works only when the root certificate is installed.

Custom Certificates

Whistle can use custom certificates (only .crt format). Place the certificate pair (e.g., test.crt and test.key) in a directory such as /data/ssl and start Whistle with w2 start -z /data/ssl, or put them in ~/.WhistleAppData/custom_certs/. Priority: -z dir > ~/.WhistleAppData/ > built‑in certificates.

Priority –z dir > ~/.WhistleAppData/ > built‑in certificates

Matching Rules

Whistle supports many matching patterns; the following cover most scenarios.

Note: The default rule format is pattern operatorURI, where the pattern is on the left and the operation on the right.

Domain Matching

# Match all requests under www.test.com (http, https, ws, wss, tunnel)
www.test.com operatorURI

# Match only http requests
http://www.test.com operatorURI

# Match only https requests
https://www.test.com operatorURI

# Limit by port
www.test.com:8888 operatorURI # port 8888
www.test.com/ operatorURI # http defaults to 80, https to 443

Path Matching

# Match only http requests
http://www.test.com/xxx operatorURI
http://www.test.com:8080/xxx operatorURI

# Match all requests under a specific path
www.test.com/xxx operatorURI
www.test.com:8080/xxx operatorURI

Wildcard Matching

Wildcard patterns start with ^; * matches a single segment, *** matches multiple segments. Use $0 for the whole URL and $1 ‑ $9 for captured groups.

# Example: map /abc/xyz/1.js to /path/to/xyz/1.js
^wy.guahao.com/abc/***   /path/to/$1
# Restrict to URLs ending with index.js
^wy.guahao.com/abc/***index.js$   /path/to/$1

Domain Wildcards

In domain matching, * does not require ^. *.com matches guahao.com but not www.guahao.com. Use ***.com to match any sub‑domain.

Regex Matching

For highly flexible rules, use regular expressions.

# Match all requests
/./ operatorURI

# Match URLs containing multiple keywords
/keyword/ operatorURI

# Capture groups example
/(\d+).html/ operatorURI

Common Features

Bind Host

Works like a hosts file entry but takes effect immediately without caching.

127.0.0.1 wy.guahao.com

Replace Request

Redirect online resources to local development servers for debugging domain‑restricted APIs.

# Local replace online
127.0.0.1 wya.guahao.com
https://wy.guahao.com http://wya.guahao.com:8080

# Proxy replace resource
^http://test.guahao-test.com/front/hps-h5-static/css/h5.min.css*** http://127.0.0.1:9091/front/hps-h5-static/css/h5.css
^http://test.guahao-test.com/front/hps-h5-static/js/h5.js*** http://127.0.0.1:9091/front/hps-h5-static/js/h5.js

Replace Response Content

Append or completely replace the response body.

# Append content
http://guahao.com/style.css resAppend://{myAppend.css}

# Replace content entirely
http://guahao.com/style.css resBody://{myResBody.css}

Inject JS Script

Inject debugging tools such as vConsole or Eruda into a page.

# Inject debugger variable (content defined in the Value panel)
https://wy.guahao.com/ htmlAppend://{debugger}

Example debugger content:

<script crossorigin="anonymous" integrity="sha384-ltIfi6+efoMR4xY0cwhn9a243JE/09cby6RJioKuqFKzs4un/eTmCLbAGaVM8xsJ" src="https://lib.baomitu.com/eruda/2.2.1/eruda.js"></script>
<script>eruda.init();</script>

Remote Console Output

Capture console logs from mobile devices and view them on a PC.

# Remote log for wy.guahao.com
wy.guahao.com log://{injection-log}

# Injection content
console.log('-----------------start-------------------')
console.log('Remote log')
console.log('Inspect variable', window)
console.log('-----------------end---------------------')

Integrate Weinre Remote Debugging

Weinre (Web Inspector Remote) provides remote debugging similar to Firebug or Chrome DevTools.

Whistle can automatically inject Weinre’s startup script, turning a multi‑step setup into a single rule.

# Integrate Weinre; [key] is any identifier
wy.guahao.com weinre://[key]

Conclusion

The features described above are the ones the author uses most frequently; Whistle offers many more capabilities, including a rich plugin ecosystem for custom needs. For full documentation and advanced usage, refer to the official Whistle documentation.