Proxy & Debug tools for macOS & Windows based on whistle https://alibaba.github.io/lightproxy/…

Download | Document | Contribute | 介绍文章 | FAQ

📦 Out-of-box, fully automation with certificate install & system proxy setting

🔋 Battery include, powerful hosts/proxy/capture based on whistle, what u need is just input /

💨 Rules take effect in one second, no hosts cache from browser

Download

macOS Version Download

Windows Version Download

Quick Start

Take a quick start at: https://alibaba.github.io/lightproxy/quick-start.html

How to contribute

env

nodejs > 12 (important)
npm install -g electron-builder if you need bundle application

dev

git clone https://github.com/alibaba/lightproxy
cd lightproxy
yarn run install-deps
yarn run dev

For new contributors you can try to fix a good-first-issue

from https://github.com/alibaba/lightproxy

https://lightproxy.org/doc/getting-started

-----------------------

LightProxy 全能代理抓包工具

LightProxy 是阿里巴巴 IFE 团队开发的一款基于 Electron 和 whistle 支持 Windows、Mac 的开源桌面代理软件

LightProxy 可以自动完成证书安装和代理设置，让开发人员能够精确的掌握自己的开发环境，通过 HTTP代理使用规则转发、修改每一个请求和响应的内容。

能帮你做什么？

抓包，包括无线场景抓包
实时 hosts 绑定
按规则转发资源
mock 接口，页面等
修改请求和响应内容，例如在页面中插入 script ，修改返回头等

下载

详细介绍：https://github.com/alibaba/lightproxy/issues/19

----------

Cross platform Web debugging proxy（fork of LightProxy、Linux & 多网卡支持）

https://www.yuque.com/iproxy

Download | Document

📦 Out-of-box, fully automation with certificate install & system proxy setting

🔋 Battery include, powerful hosts/proxy/capture based on whistle, what u need is just input /

🔌 Hackable, you could write even Node.js for your proxy rule

Preview GIF

Download

macOS/Windows/Linux

About Linux Version

iProxy supports Linux now! It is contributed by the Deepin Beijing Develop Team.

Supported desktop environment: Gnome and DDE.

Supported linux distribution: Debian, Ubuntu, deepin, etc.

Unsupported desktop environment: KDE.

Fedora and Arch Linux: please replace libnss3-tools with the package name of your distribution.

Quick Start

Take a quick start at: https://yuque.com/iproxy

How to contribute

env

nodejs > 12 (important)
npm install -g electron-builder if you need bundle application

dev

git clone https://github.com/xcodebuild/iproxy
cd iproxy
yarn run install-deps
yarn run dev

from  https://github.com/xcodebuild/iProxy

-----

CLI helper for iProxy.

iproxy-cli

npm install -g iproxy-cli

iproxy.config.js

Put your proxy rule in iproxy.config.js.

module.exports = {
    id: 'rule id',
    name: 'rule name',
    rule: `# Rule contnet`,
};

enable

Run iproxy to active rule, ctrl-c to interrupt program then disable rule.

from https://github.com/xcodebuild/iproxy-cli

------

HTTP, HTTP2, HTTPS, Websocket debugging proxy.

https://wproxy.org/

English | 简体中文

We recommend updating whistle and Node to ensure that you receive important features, bugfixes and performance improvements. Some versions of Node have bugs that may cause whistle to not work properly, for detail see the issue: #231

whistle

中文 README

whistle is a cross-platform web debugging tool based on Node.js.

It features the following:

offer HTTP proxying
capture, replay or compose requests of HTTP, HTTPS, WebSocket and TCP.
manipulate http request and response by configing hosts, or patterns like domain, path, regular expression, wildcard characters, wildcard path, etc.
offer build-in mobile debugging mode

If the aboves can't satisfy your requirements, you can also use plugins to extend its capabilities.

The specific functions are as follows：

Manipulations to http request and response in whistle can be achieved as a Rule looks like:

pattern operatorURI

Description：

pattern is an expression to match the target request url. You can write patterns in different forms including domain, path, regular expression, wildcard, and so on.

 # matching domain
 www.example.com
 # domain with port
 www.example.com:6666
 # domain with protocol, supporting http, https, ws, wss, tunnel
 http://www.example.com

 # matching path, supporting protocol, port
 www.example.com/test
 https:/www.exapmle.com/test
 https:/www.exapmle.com:6666/test

 # matching regular expression
 /^https?://www\.example\.com\/test/(.*)/ referer://http://www.test.com/$1

 # matching wildcard
 ^www.example.com/test/*** referer://http://www.test.com/$1

For more details, please visit Pattern Matching

operatorURI is the corresponding operation, made up of opProtocol and opValue：
opProtocol represents the kind of operation, e.g.

 # host：setting requested server IP
 pattern host://opValue

 # file：using the local file to replace
 pattern file://opValue

opValue represents the parameters of the specific operation, e.g.

 # host：setting requested server IP
 pattern host://127.0.0.1:6666 # or pattern 127.0.0.1:6666	

 # file：using the local file to replace
 pattern file:///User/test/dirOrFile # or pattern /User/test/dirOrFile
 pattern file://E:\test\dirOrFile # or pattern E:\test\dirOrFile

For more details, please visit operation value

The position of pattern and operatorURI can be swapped in most situations while the combination mode is also supported. For more details, please visit configuration mode

Install & Setup

install Node

The latest LTS version of Node.js is recommended.

If none or low version of Node.js is installed, you need install the latest version of Node.js according to the following instructions：

For Windows: please visit https://nodejs.org/ to download the latest LTS version of Node.js and then, install it using the default options.
For Mac: the same as Windows.
For Linux: using source code to install is recommended, because in this way, you don't need to configure the path. If you fail to install with source code, you can also use the binary version of Node.js directly.
- with source package： visit Official website of Node to download the latest version of Source Code*(or using wget in shell), unzip(tar -xzvf node-xxx.tar.gz), switch to the root directory(cd node-xxx), execute ./configure, ./make and ./make install in order。
- using binary version：visit Official website of Node to download the latest Linux Binaries(or using command wget to download), unzip(tar -xzvf node-xxx.tar.gz), add the absolute path of bin directory to system PATH after extracting。

You can execute node -v in shell to check if the expected version of Node.js is installed successfully：

$ node -v
v8.9.4

install whistle

After the Node.js is installed successfully, you can execute the following npm command to install whistle（In Mac or Linux, prefix sudo is needed if you are not root user, i.e. sudo npm install -g whistle）

npm install -g whistle

In China, you can install whistle using npm mirror of taobao to speed up installing progress and avoid failure：

npm install cnpm -g --registry=https://registry.npm.taobao.org
cnpm install -g whistle

or specify mirror install directly：
npm install whistle -g --registry=https://registry.npm.taobao.org

After installation, execute whistle help or w2 help to view help information:

$ w2 help
Usage: whistle <command> [options]


Commands:

	run       Start a front service
	start     Start a background service
	stop      Stop current background service
	restart   Restart current background service
	help      Display help information

Options:

	-h, --help                                      output usage information
	-D, --baseDir [baseDir]                         the base dir of config data
	-z, --certDir [directory]                       custom certificate path
	-l, --localUIHost [hostname]                    local ui host (local.whistlejs.com by default)
	-n, --username [username]                       the username of whistle
	-w, --password [password]                       the password of whistle
	-N, --guestName [username]                      the guest name
	-W, --guestPassword [password]                  the guest password
	-s, --sockets [number]                          max sockets (60 by default)
	-S, --storage [newStorageDir]                   the new local storage directory
	-C, --copy [storageDir]                         copy storageDir to newStorageDir
	-c, --dnsCache [time]                           the cache time of DNS (30000ms by default)
	-H, --host [host]                               whistle listening host(:: or 0.0.0.0 by default)
	-p, --port [port]                               whistle listening port (8899 by default)
	-P, --uiport [uiport]                           whistle ui port (8900 by default)
	-m, --middlewares [script path or module name]  express middlewares path (as: xx,yy/zz.js)
	-M, --mode [mode]                               the whistle mode (as: pureProxy|debug|multiEnv)
	-t, --timeout [ms]                              request timeout (66000 ms by default)
	-e, --extra [extraData]                         extra data for plugin
	-f, --secureFilter [secureFilter]               the script path of secure filter
	-R, --reqCacheSize [reqCacheSize]               the cache size of request data (512 by default)
	-F, --frameCacheSize [frameCacheSize]           the cache size of socket frames (512 by default)
	-V, --version                                   output the version number

Setup whistle

Start:

w2 start

Note: If you don't want others to visit the configuration page of whistle, just add username and password when start, i.e. -n yourusername -w yourpassword。

Restart:

w2 restart

Stop:

w2 stop

Debugging mode:

w2 run

For more details, please visit install and start

Proxing Settings

configuring server & port

proxying server：127.0.0.1(if whistle is deployed in remote server or virtual machine, change this address to corresponding IP address)
default port：8899(if port 8899 is used already, you can specify new port using -p when start. More details can be visited by executing whistle help or w2 help (only supported in v0.7.0 and higher version)

Make sure using the same proxying server for all protocol in system proxying setting is checked.

Browser & System configuration

proxy setting in OS：

proxy setting in browser(recommended)
- for Chrome：intall chrome plugin whistle-for-chrome or Proxy SwitchySharp
- for Firefox： Open Options page in Firefox, then switch to General -> Network Proxy, then set Manual proxy configuration to whistle.
in mobiles, configure the proxy of current Wi-Fi in Setting

PS: The mobile may failed to use network after configuration because the firewall of the PC has forbidden remote visit to the whistle's port. you can try to close the firewall or configure white list ： http://jingyan.baidu.com/article/870c6fc317cae7b03ee4be48.html

For more details, please vsit install and start

Visit whistle's operation page

After the above steps are completed, open the whistle page in browserhttp://local.whistlejs.com：

There are five main tabs in the navigation bar:

Network

check and compose the http request
show the console print and javascript errors thrown in pages

Rules：configure rules for manipulating
Plugins

show the list of installed plugins
enable or disable installed plugins

Weinre：configure Weinre list
HTTPS：
- configure whether or not to intercept the HTTPS and download the root certificate for whistle

Certificate Installment

Please install root certificate and enable HTTPS interception before using whislte.

For more details, please vsit Certificate Installment

Quick start

Open Rules tab in whistle, and create a group named test by context menu or Create button in menu bar. Then follow the next steps to write rules and save.

cofigure hosts
Specify the ip of www.ifeng.com:
```
 www.ifeng.com 127.0.0.1
 # or
 127.0.0.1 www.ifeng.com
```
Specify the ip and port of www.ifeng.com to forward http request to local port 8080. In this way, we can visit the local website just as online when the developing port is not 80:
```
 # www.ifeng.com 127.0.0.1
 www.ifeng.com 127.0.0.1:8080
 # or
 127.0.0.1:8080 www.ifeng.com
```
We can also replace the real IP (or domain) and port with any domain without port:
```
 www.ifeng.com host://www.qq.com:8080
 # or
 host://www.qq.com:8080 www.ifeng.com
```
For more details, please visit Pattern Matching
local files replacing

Replace the response with content in local file system, which is frequently used during web developing.

# Mac or Linux
www.ifeng.com file:///User/username/test
# or www.ifeng.com file:///User/username/test/index.html
	
# Both '\' and '/' can be used as path separator for Widows
www.ifeng.com file://E:\xx\test
# or www.ifeng.com file://E:\xx\test\index.html

http://www.ifeng.com/ will try to load /User/username/test first. If the former dosen't exist, the file /User/username/test/index.html will be loaded. For neither exists, it returns 404.

To replace jsonp request, you can refer to tpl

For more details, please vsit Pattern Matching

Request Forward
To forward all the requests from domain www.ifeng.com to domain www.aliexpress.com
```
 www.ifeng.com www.aliexpress.com
```
For more details, Pattern Matching
Inject html、js、css
whistle will decide whether injecting corresponding text and how to inject, like whether wrapping the text with HTML label, automatically according to response type.
```
 # Mac、Linux
 www.ifeng.com html:///User/xxx/test/test.html
 www.ifeng.com js:///User/xxx/test/test.js
 www.ifeng.com css:///User/xxx/test/test.css
 
 # Both '\' and '/' can be used as path separator for Widows
 www.ifeng.com html://E:\xx\test\test.html
 www.ifeng.com js://E:\xx\test\test.js
 www.ifeng.com css://E:\xx\test\test.css
```
For all the requests for domain www.ifeng.com, whistle will inject the processed text to response body according to response type. If the type is HTML, the js content will be wrapped within script, and the css content be wrapped within style to be injected to response body。
For more details, Pattern Matching
Debug for remote page
With the protocol weinre and protocol log provided by whistle, you can modify the DOM structure, capture the javascript errors and view the console print easily. Moreover, you can inject specified script to debug the remote page.
Before using whistle to debug remote page, you need to set the proxy for OS or browser to whistle. Please refers Install and start to know how to set the proxy.
For weinre：
```
 www.ifeng.com weinre://test
```
Add the following rule in group named test and save, open the www.ifeng.com with a new tab in browser. Then you can see a list when you hover over the button weinre, click the item test to open a weinre debug page. For example, you can see the DOM structure when swich to Elements tab after selected a target.
For log:
```
 www.ifeng.com log://{test.js}
```
Add the following rule in group named test and save. Then you can see a list when you hover over the button Values, whistle will create a group named test.js in Values when you click it. Input the text console.log(1, 2, 3, {a: 123}) in the group editor, open the Network -> Log -> Console, open the www.ifeng.com, you can see the output '1, 2, 3, {a: 123}' in Console panel.
For more details, Pattern Matching and Rules

Documentation

from https://github.com/avwo/whistle

---------------------------------------------------------

LightProxy 是 IFE 团队开发的一款基于 Electron 和 whistle 的开源桌面代理软件，致力于让前端开发人员能够精确的掌握自己的开发环境，通过 HTTP 代理使用规则转发、修改每一个请求和响应的内容。

为什么需要一个代理工具

因为代理工具能够让你随心所欲的掌控自己当前的开发环境。

开发环境是影响研发效能最大的一个因素之一，不可用的环境，无法完成的部署，不稳定的上游环境等等都让一个非常简单的需求轻松消耗掉数天的时间。

当开发环境陷入一种不健康的状态时，开发者就更容易破罐子破摔。宁可忍受每改一行代码重新手动 build 几分钟再开发也不愿意花时间让 watch 可用，然后发现自己越来越忙乱。

希腊神话中有一个受到惩罚的人西西弗斯，他受罚的方式是：必须将一块巨石推上山顶，而每次到达山顶后巨石又滚回山下，如此永无止境地重复下去。在西方语境中，形容词“西西弗斯式的”（英语：sisyphean）形容“永无尽头而又徒劳无功的任务”。

当你的接口和页面突然不能工作时，代理工具可以快速 mock 一个。当你想测试一下线上页面改动可能会带来的后果，代理工具可以让你不经过复杂的发布过程快速在本地看到想要的效果。

什么是好的开发环境

既然我们在讨论开发环境对于研发效率的影响，那我们先来看一看什么是好的前端开发环境。

稳定

好的开发环境首先应该是稳定可用的，不应该在开发测试的过程中频繁挂掉或者频繁发生改变。
依赖于后端日常接口进行调试的前端对这点应该深有体会，自己的问题还没解决，环境就时常带来新的问题。

快速验证

修改代码能够在尽可能短的时间内得到验证也是一个基本诉求，这也是为什么大部分前端构建都会关注 Hot reload 和更高级的 HMR 。

有些场景下的修改一次简单的修改就要经过长时间的等待，例如依赖上游修改接口的返回内容，需要修改后端的页面结构然后重新部署，需要走一遍完整的发布流程来测试某个修改在真实的线上页面会产生的影响等等。

这种改一行等几十分钟的开发方式对效率的拖累是极其恐怖的。

和线上的一致性

很多项目的线上环境极为复杂，为了解决日常开发中的问题，也会有一个线下的 DEMO 页面，最后开发完再搬到线上。

这种方式相对来说较为稳定且能快速验证，但比较凸显的问题在于和线上并不一致。开发中会存在很多 if-else 的逻辑，例如最常见的：

1	const API_BASE = utils.isDaily ? 'http://localhost:7001:': 'https://xxxx/';

这种情况也往往导致 Bug 非常难以被定位，最后逼着开发者退化到在线上环境低效的进行 debug。

确定性

开发者对于当前的环境应该是有确切认知的，而不是一直不停的怀疑自己的配置到底有没有生效，命中的是不是又是缓存等等。

有些情况下我们利用 hosts 切换工具来进行联调，但在切完 hosts 后却又不得不来回确认自己的切换是否生效，清楚 Chrome 的 DNS Cache，清楚 Socket 之类的。

这种非确定性不但提高了开发者心智负担，而且也会导致 Bug 难以定位。

LightProxy 如何解决这些问题

那么 LightProxy 要如何解决上面的这些问题呢

LightProxy 通过基于 whistle 的代理能力，能够任意修改开发环境中的 request 和 response 。

举个例子

例如当我们需要在线上页面中加入一个 DIV ，如果没有代理我们需要依赖后端一套类似的预发环境，而有了 LightProxy 我们只需要使用：

1	https://www.alibaba.com/ htmlPrepend://( test )

就可以在一个线上的页面中插入一个 div 。

同样的，我们可以直接把页面中的一个 JS 转发到本地一个开发中的文件

1	https://www.google.com/xx.js file:///User/xxx/xxx.js

当后端缺少 CORS 头时，我们可以直接给它先加上 CORS 头

1	https://xxx.com/xx.json resCors:// # 给响应的请求增加 CORS header

也可以直接把某个文件变成一个内联的文字，只要用类似 ES6 字符串框起来

1	https://xxx.com/xx.json `test text`

总体来说，LightProxy 能够让开发者完全掌控自己的开发环境，用极低的成本定制自己的开发环境，而不是总是在等待依赖方按照自己的需求提供相应的环境。

甚至于，你可以自己用 NodeJS 书写针对某个规则的响应：使用 NodeJS 编写规则

快速确认

为了能够快速确认代理是否按预期工作，我们在经过 LightProxy 代理的网络请求的 Response Header 增加了一些相关的信息，用于协助开发人员快速确认当前请求命中了什么规则，以及这个请求是怎么来的（由谁响应，匹配什么规则，实际真正访问的来源）。

没有银弹

虽然说代理工具可以快速的解决各种开发环境上的坑，但也并不是银弹。

这种方案更加适合在开发阶段快速绕过各种拦路虎，但最终在多人协作中仍然需要有健康的环境来保障项目的协作流程流畅，不能因为有了代理工具后就完全无视开发环境的问题。

开始 & 下载

说了这么多，开始使用 LightProxy 控制你的开发环境吧：https://github.com/alibaba/lightproxy

下载

macOS 版
Windows 版

Pages

Wednesday, 22 April 2020