What are common issues with whistle and how to troubleshoot and solve them?

Answer

Whistle may encounter various issues during actual use. Understanding common problems and their solutions can improve work efficiency.

Installation and Startup Issues

1. Installation Failure

Problem:

bash
npm install -g whistle
# Error: EACCES: permission denied

Solutions:

Method 1: Use sudo (Mac/Linux)

bash
sudo npm install -g whistle

Method 2: Modify npm directory permissions

bash
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules

Method 3: Use nvm

bash
nvm install node
nvm use node
npm install -g whistle

2. Startup Failure

Problem:

bash
w2 start
# Error: Port 8899 is already in use

Solutions:

Method 1: Find and kill process occupying port

bash
# Mac/Linux
lsof -i :8899
kill -9 <PID>

# Windows
netstat -ano | findstr :8899
taskkill /PID <PID> /F

Method 2: Use different port

bash
w2 start -p 8080

Method 3: Stop previous whistle instance

bash
w2 stop
w2 start

3. Cannot Access After Startup

Problem: Started successfully but cannot access http://127.0.0.1:8899/

Solutions:

Check if whistle is running:

bash
w2 status

Check firewall settings:

• Windows: Allow whistle through firewall
• Mac: System Preferences → Security & Privacy → Firewall
• Linux: Check iptables or ufw settings

Check if port is correct:

bash
# View listening port
netstat -an | grep 8899

Configuration Issues

1. Rules Not Taking Effect

Problem: Configured rules but not taking effect

Solutions:

Check rule syntax:

• Ensure rule format is correct
• Check for syntax errors
• Check if rules are commented out

Check rule priority:

• More specific rules should be placed earlier
• Check for rule conflicts

Restart whistle:

bash
w2 restart

Clear browser cache:

• Clear browser cache and cookies
• Test in private mode

2. HTTPS Interception Failure

Problem: Cannot intercept HTTPS requests

Solutions:

Check if HTTPS interception is enabled:

1. Visit http://127.0.0.1:8899/
2. Click "HTTPS" tab
3. Check "Capture HTTPS"

Check if certificate is correctly installed:

• Download root certificate
• Install to trusted root certificate authorities
• Restart browser

Use rule to enable HTTPS:

shell
pattern whistle.https://

3. Proxy Configuration Error

Problem: Browser cannot access network through whistle proxy

Solutions:

Check proxy configuration:

• Confirm proxy address is correct: 127.0.0.1:8899
• Confirm proxy type: HTTP proxy
• Confirm no PAC file configured

Test proxy connection:

bash
curl -x http://127.0.0.1:8899 http://www.example.com

Check network connection:

• Confirm computer can access network
• Check DNS settings

Performance Issues

1. Whistle Running Slowly

Problem: Whistle responds slowly, affecting development efficiency

Solutions:

Clear cache:

bash
w2 clean cache

Reduce number of rules:

• Delete unnecessary rules
• Use more precise matching patterns

Increase memory limit:

bash
node --max-old-space-size=4096 $(which w2) start

Upgrade to latest version:

bash
npm update -g whistle

2. High Memory Usage

Problem: Whistle occupies large amount of memory

Solutions:

View memory usage:

bash
w2 memory

Limit log size:

bash
w2 log clear

Regularly restart whistle:

bash
w2 restart

Optimize rules:

• Avoid using complex regular expressions
• Reduce script processing

3. High CPU Usage

Problem: Whistle occupies large amount of CPU

Solutions:

View CPU usage:

bash
w2 cpu

Check plugins:

• Disable unnecessary plugins
• Update plugins to latest version

Optimize scripts:

• Reduce complex calculations in scripts
• Use async operations

Mobile Issues

1. Phone Cannot Connect to Proxy

Problem: Configured phone proxy but cannot connect

Solutions:

Check network connection:

• Confirm phone and computer on same Wi-Fi
• Test if phone can access computer IP

Check proxy configuration:

• Confirm proxy address is computer IP
• Confirm proxy port is 8899
• Confirm proxy type is HTTP

Check firewall:

• Allow whistle through firewall
• Allow 8899 port inbound connections

2. HTTPS Certificate Installation Failure

Problem: Phone cannot install or trust HTTPS certificate

Solutions:

iOS device:

1. After downloading certificate, open "Settings" → "Downloaded Profile"
2. Install certificate
3. Go to "Settings" → "General" → "About" → "Certificate Trust Settings"
4. Enable "Full Trust"

Android device:

1. Open after downloading certificate
2. Follow prompts to install
3. Go to "Settings" → "Security" → "Encryption & credentials" → "Trusted credentials"
4. Confirm certificate is installed

Restart phone browser

3. Some Apps Cannot Be Intercepted

Problem: Some app requests cannot be intercepted by whistle

Solutions:

Check if app uses system proxy:

• Some apps don't use system proxy
• Need to use VPN mode

Check certificate pinning:

• Some apps use certificate pinning
• Need to use Frida or other tools

Check network library:

• Some apps use custom network libraries
• Need reverse engineering

WebSocket Issues

1. WebSocket Connection Failure

Problem: WebSocket cannot establish connection

Solutions:

Check proxy rules:

shell
ws://example.com host 127.0.0.1:8080

Check server support:

• Confirm server supports WebSocket
• Check if WebSocket port is open

Check firewall:

• Allow WebSocket port
• Check proxy settings

2. WebSocket Message Loss

Problem: Some WebSocket messages are lost

Solutions:

Check network stability:

• Use stable network
• Avoid frequent network switching

Check server load:

• Server may be overloaded
• Increase server resources

Check heartbeat mechanism:

• Implement heartbeat detection
• Auto-reconnect mechanism

Plugin Issues

1. Plugin Installation Failure

Problem: Cannot install whistle plugin

Solutions:

Check npm registry:

bash
npm config get registry
# If not official registry, switch to official
npm config set registry https://registry.npmjs.org/

Check network connection:

• Ensure access to npm registry
• Use proxy or mirror

Use Taobao mirror:

bash
npm config set registry https://registry.npmmirror.com/

2. Plugin Runtime Error

Problem: Plugin runs with errors after installation

Solutions:

View error logs:

bash
w2 log

Check plugin version:

• Confirm plugin version is compatible with whistle version
• Update plugin to latest version

Check plugin dependencies:

• Install plugin dependencies

bash
npm install

Data Issues

1. Configuration Loss

Problem: Whistle configuration accidentally lost

Solutions:

Restore from backup:

bash
cp ~/.whistle/rules.backup ~/.whistle/rules

Restore from Git:

bash
git checkout ~/.whistle/rules

Reconfigure:

• Re-add rules
• Reinstall plugins

2. Log Too Large

Problem: Whistle log file is too large

Solutions:

Clear logs:

bash
w2 log clear

Set log rotation:

bash
w2 log rotate

Regular cleanup:

bash
# Create scheduled task to clean logs
crontab -e
# Add: 0 0 * * * w2 log clear

Best Practices

1. Regularly Backup Configuration

   • Use Git to manage configuration
   • Regularly export configuration files
   • Keep historical versions

2. Keep Updated

   • Regularly update whistle
   • Update plugins to latest version
   • Follow official announcements

3. Monitor Resource Usage

   • Regularly check memory and CPU
   • Clear cache in time
   • Optimize rules and scripts

4. Document Configuration

   • Add rule comments
   • Write configuration documentation
   • Record problem solutions

5. Use Script Automation

   • Automate common operations
   • Reduce manual operations
   • Improve work efficiency