EnvProxy — 终端自动翻墙（环境变量代理）

简体中文 | English

翻墙软件只管浏览器，不管终端。git、npm、curl 这类工具靠一组叫「环境变量」的设置知道代理的地址，才连得上外面。

EnvProxy 自动维护这组设置。翻墙软件开着，它把代理地址写进去；关掉，它删掉。日常不需要记任何命令。

0. 装完之后会发生什么
1. 安装（3 步，5 分钟）
2. 打开菜单
3. 常用操作一页纸
4. 出问题了按这个顺序查
5. 它是怎么判断在不在翻墙的
6. 为什么它不容易出错
7. 性能与流量
8. 文件夹里都有什么
9. 关于复制备份文件夹
10. 给朋友/新电脑部署
11. 技术边界（5 条）
12. macOS 版
13. 许可证与问题反馈

0. 装完之后会发生什么

装完之后绝大多数情况都不用管。下面三种情况里，只有第一种什么都不用做，另外两种最多就是重开一个窗口。

你的情况	会发生什么	需要做什么
装完之后新开的窗口或程序	启动时读到的就是当前状态	什么都不用做
窗口一直开着，后来代理又变了	窗口里还是旧状态	按一次回车（cmd 窗口只能重开）
装之前就已经开着的窗口	安装时那段同步代码还没装进去	重开一个窗口；不想重开就照 3.1 里的命令手动加载一次

为什么开着的窗口要按一次回车

每个程序只在启动那一刻读一次环境变量，读完就固定了。之后系统里改了，已经在运行的窗口不会跟着变。

所以新窗口自动是对的，老窗口得让它重读一次。EnvProxy 挑的时机是每次命令执行完、屏幕重新出现光标的时候——你本来就在一直敲命令，不用专门做什么。

AI 工具、编辑器、IDE

它们开终端一般是新开一个进程，所以自动就是对的。

两种要重启那个工具：装 EnvProxy 之前就开着的；或者它是常驻后台、不随用随开的。拿不准就重启一次。

1. 安装（3 步，5 分钟）

点 这里下载 Windows 版安装包（Mac 版点 EnvProxy-mac.tar.gz）
解压到任意位置，文件夹可以改名。进 win 双击 打开菜单.cmd（Mac 进 mac 双击 打开菜单.command），选 1 安装 / 修复
看到「监控进程：已启动」就好了

安装会做四件事：① 把你原来的变量值存一份（卸载时还原）；② 设置开机自启；③ 往终端配置里加一段同步代码；④ 启动监控，并把变量按当前状态校正一次。

屏幕上按 1–4 报进度，顺序两端略有不同：Windows 是 ①自启 ②监控 ③变量 ④终端同步，Mac 是 ①自启 ②终端同步 ③监控 ④变量。第 ① 件事在编号开始之前就做完了，不占一行。

出问题就打开菜单选 1 安装 / 修复。它能修好大部分问题，重复运行不会多装一份，不会中断网络，也不会丢失你的设置。

从网上下载的包第一次双击如果被拦截：右键文件 → 属性 → 解除锁定（或运行 Unblock-File .\EnvProxy-win.zip），不要修改执行策略。

更新

打开菜单选 3 检查更新：先说明最新版本号和这一版改了什么，同意之后才安装。

升级不需要开翻墙软件：多数网络本来就能连。如果提示连不上，把翻墙软件开关一次再试。
安装前核对校验值：下载完成后先核对，对不上就不安装。装坏了比不装更麻烦。老版本发布的文件没有附带校验值，或者文件刚下完被杀软锁住读不出来时，会跳过这一步继续安装。
只替换程序文件：你的文件、日志、monitor\ 里的运行标记都不会被改动。安装完成后监控用新代码重启。

2. 打开菜单

双击 打开菜单.cmd（Mac 是 打开菜单.command）。它只负责把选择的编号转给真正的程序执行，自己不改动任何文件。

菜单按使用频率分三组，编号从上往下连续，不用记：

菜单项	做什么	影响哪些部分
日常
1 安装 / 修复	第一次用选它；觉得不对劲也选它	开机启动 + 终端同步脚本 + 环境变量 + 后台监控
2 查看状态	监控、代理、终端同步、环境变量、版本	只读取，不改动
3 检查更新	先说明改了什么，同意才安装	只替换程序文件，然后重启监控（用新代码）
4 帮助	忘记怎么用就看它	只打印文字，不改动
维护
5 停止监控	临时停用，下次登录会恢复	监控进程 + 环境变量
6 一键恢复	完全卸载，回到安装之前	全部清除（日志可选保留）
退出
0 退出	关闭菜单	无

直接按回车等于查看状态，这是最常看的一项。菜单顶部会显示监控是否在运行、当前版本号，不需要进去看。

菜单和帮助里的操作只有两种：输编号做那件事；直接回车是往回走——在主菜单里等于查看状态，在帮助里等于退回上一级。不用记别的键。

选 4 进帮助，按你遇到的问题挑：

编号	一条回答一个问题
1	这是干什么用的
2	装完之后要我做什么
3	这个窗口固定直连 / 恢复自动
4	这个窗口走公司代理
5	我要让某条命令不走代理
6	菜单每一项是干什么的
7	装了还是连不上网 / 状态不对
8	还是不行 / 想删掉它

进去以后底部会列出全部编号，你在哪一条一眼就看得到。

日志

monitor\monitor.log（Mac 是 mac/monitor/monitor.log）记录它做过的判断。上限 200KB，写满之后只保留最近 200 行。

卸载时会询问是否保留，选择保留就只留这一份，其余全部清除。

3. 常用操作一页纸

平时不用读这一节。 翻墙软件一开一关，终端自己就跟着切，不用敲任何命令。只有想单独管某个窗口、或者想确认到底装没装上，才往下看。

每一小节都能单独看，不用按顺序读。

先认一下你在用哪个终端。四种写法不一样，命令也不一样：

提示符长这样	你用的是	怎么打开
`PS C:\...>`	PowerShell（Windows 自带）	开始菜单搜 PowerShell
`C:\...>`	cmd（命令提示符，Windows 自带）	开始菜单搜「命令提示符」
`名字@主机 MINGW64 ~ $`	Git Bash（Windows 上的 bash）	开始菜单搜 Git Bash
`名字@主机 ~ %`	Mac 的「终端」（默认是 zsh）	启动台搜「终端」

三个容易搞混的地方：

Git Bash 是 Windows 的东西，装 Git for Windows 时一起装的，Mac 上没有这个名字。它和 Mac 的终端都用 bash 那套写法，所以下面经常合在一起讲。
Mac 的「终端」默认不是 bash 是 zsh，提示符结尾是 % 而不是 $。写法和 bash 一样，按下面的命令敲就行。
Windows Terminal 只是「装终端窗口的壳」，里面开的是 PowerShell、cmd 还是 Git Bash 由你选——它本身不是一种终端。

会自动跟随的：PowerShell、Git Bash、Mac 终端（zsh 和 bash 都行）。不会的：cmd（没有钩子可用）和 fish（Mac 上另一个 shell，钩子读不到它）。

3.1 已经开着的窗口，敲一下回车就更新

EnvProxy 跟着翻墙软件走：软件连上，终端就用代理；软件断开，终端就恢复直连。新开的窗口永远是最新的。

已经开着的窗口不会自己变——每个程序只在启动那一刻读一次环境变量，之后系统再改它也看不见。让它更新只要在那个窗口里敲一下回车（或者随便跑一条命令）。

你的窗口	现在是什么状态	要做什么
装完之后打开的	已经是最新的	不用管
一直开着，中途翻墙软件开关过	还是旧状态	敲一下回车
装 EnvProxy 之前就打开的	从来没装过同步代码	重开一个窗口

cmd 窗口只能重开，敲回车没用——它没有「每次回到提示符跑一小段命令」这个机制。

不想重开、也不想敲回车，可以手动加载一次：

窗口	命令
PowerShell	`. $PROFILE`
Git Bash	`source ~/.bashrc`
Mac 终端	`. ~/.envproxy/prompt-sync.sh`

开头的 . 和它后面的空格都不能少，意思是「在这个窗口里执行这个文件」。只影响当前这个窗口，别的已开窗口要各自来一次。如果这个窗口从来没装过 EnvProxy，会看到「找不到路径」的红字——正常，重开一个窗口就行。

3.2 固定直连 / 恢复自动

让这个窗口固定直连

想让这一个窗口不走代理，就在它里面设一个开关。

PowerShell

$env:ENVPROXY_TERM = 'off'

Git Bash / Mac 终端

export ENVPROXY_TERM=off

设上之后，下一次回到提示符时代理变量就会被清掉，之后一直直连（同一条命令行里接着跑的那条命令用的还是旧值）。

cmd 没有这个开关（它不支持钩子），只能自己把 5 个变量清掉。一行一条：

set HTTP_PROXY=
set HTTPS_PROXY=
set ALL_PROXY=
set NO_PROXY=
set NODE_USE_ENV_PROXY=

写成一行也行：

set HTTP_PROXY=&set HTTPS_PROXY=&set ALL_PROXY=&set NO_PROXY=&set NODE_USE_ENV_PROXY=

& 两边不要留空格。留了的话，变量值是一个空格而不是空，代理照样生效。

别用 unset HTTP_PROXY ...：钩子往 Git Bash 里写的是小写拼写（http_proxy 等）， unset 大写的那个清不掉小写的，Git Bash 里的 curl 认小写，照样走代理。而且下一个提示符会把它们重新写回来。用上面的开关才是真接管。

要改回来（重新跟着翻墙软件走）

窗口	命令
PowerShell	`Remove-Item Env:ENVPROXY_TERM`
Git Bash / Mac 终端	`unset ENVPROXY_TERM`
cmd	重开一个窗口

这些改动只在这个窗口有效，窗口一关就没了。

3.3 让这个窗口走公司代理

两步，顺序不能反：先按 3.2 固定直连，再设地址。不停掉自动跟随，翻墙软件一有变化就会覆盖你刚设的地址。

下面的 你的地址:端口 换成公司给你的——问 IT 要，通常会给一份代理设置说明。这里不是翻墙软件那个端口，别去那儿找。

PowerShell：

$env:HTTPS_PROXY = 'http://你的地址:端口'

cmd：

set HTTPS_PROXY=http://你的地址:端口

Git Bash / Mac：

export HTTPS_PROXY=http://你的地址:端口

你自己设的值不会被删——只要和我们写入的不一样，公司代理、抓包工具、别的端口都原样留着。

看现在走不走（有值就是走，空的是直连）：

PowerShell	cmd	Git Bash / Mac
`$env:HTTPS_PROXY`	`set HTTPS_PROXY`	`echo $HTTPS_PROXY`

3.4 让某一条命令不走代理

不同工具写法不一样，也没有通用的一条命令。

工具	PowerShell	cmd	Git Bash / Mac
`curl`	`curl.exe --noproxy "*" 网址`	`curl --noproxy "*" 网址`	`curl --noproxy '*' 网址`
`git`	`git -c http.proxy= -c https.proxy= clone 仓库地址`	同左	同左
`npm`	`npm --noproxy=registry.npmjs.org install 包名`	同左	同左
`wget`	系统不自带；装过才有 `wget.exe --no-proxy 网址`	同左	`wget --no-proxy 网址`
`docker`	改 Docker 自己的设置，没有单条命令的写法	同左	同左

三个坑，都是实测出来的：

只有 PowerShell 5.1 里 curl 和 wget 是别名，指向 Invoke-WebRequest，直接敲会报「参数找不到」，所以那里要写 curl.exe。cmd 和 PowerShell 7 里 curl 就是真的 curl.exe，正常写就行。
npm 的 --noproxy 只认域名，写 * 没用。它不报错，请求照样走代理，你会以为绕过了。要写具体域名。
npm --no-proxy 会被当成 --proxy=false，和「不走代理」不是一回事。用 --noproxy=域名。

另外：git 的 -c http.proxy= 后面必须留空，留空是「这条命令不用代理」，写别的值就是「改用那个代理」。npm 只认 HTTPS_PROXY，不认 HTTP_PROXY——EnvProxy 两个都写，所以 npm 能正常走。

这些参数都是各工具自己的，不是 EnvProxy 提供的。不加这些参数时，它们读的才是 EnvProxy 写入的变量。

3.5 怎么确认它真的装上了

菜单选 2 查看状态，看「终端同步」那一行：

显示	意思	怎么办
已生效	正常	什么都不用做
装了但跑不起来（附原因）	Windows 执行策略不让 PowerShell 跑配置文件。只有 Windows 会有这一行	按它的提示改一次（见第 4 节），改完重开一个窗口
配置文件里的标记不成对	你的配置文件被别的工具改过	重跑一次「1 安装 / 修复」
配置文件里没有同步块	从没装上，或者被清理过	重跑一次「1 安装 / 修复」
这一轮读不到配置文件路径（只有 Windows 会显示）	极少见，这一轮判断不了	过几秒再看一次；一直在就重跑一次「1 安装 / 修复」

3.6 不开菜单也能用（写脚本、远程连接）

菜单适合双击着用。写脚本、或者通过远程连接上来没有图形界面时，用命令行参数。前六行与菜单里的六项一一对应；最后两行菜单里没有。

想做的事	Windows	Mac
安装 / 修复	`-Install`	`install`
查看状态	`-Status`	`status`
检查更新	`-Update`	`update`
帮助	`-Help`	`help`
停止监控	`-Stop`	`stop`
一键恢复	`-Uninstall`	`uninstall`
打开菜单	`-Menu`	`menu`
自检（排查用）	—	`self-test`

顺序和菜单里一样：先是日常四项，再是维护两项。最后一行是 Mac 独有的排查命令：它在一个临时沙箱里跑一遍内部检查，不碰你的配置文件和环境变量。

-Purge（Mac 是 --purge）只配一键恢复用，表示连日志一起删。-Yes（Mac 是 --yes）只配检查更新用，表示不再问「要不要装」。

先进入程序所在的目录，再敲命令。不做这一步会报「找不到文件」，因为程序在 win\ 和 mac\ 里。

Windows（cmd 或 PowerShell 都行）：

cd win
powershell -ExecutionPolicy Bypass -File envproxy.ps1 -Status

macOS（终端）：

cd mac
bash envproxy.sh status

参数必须写全，不支持缩写。-Instal 少一个字母会被拒绝——这是故意的，否则敲错一个字母就变成真安装。

4. 出问题了按这个顺序查

按顺序排查，上一步试完再往下走。

你看到的	最可能的原因	怎么办
提示「无法识别的开关」（Windows）或「无法识别的参数」（Mac）	参数打错，或者用了缩写	参数必须写全，不支持缩写。对照菜单里列出的写法
终端还是不能翻墙	这个窗口是安装之前打开的	重新打开一个窗口。不想重开就照 3.1 的办法加载一次
终端还是不能翻墙，重新打开也不行	监控没有在运行	打开菜单选 1（安装 / 修复）
提示「安装不完整，缺少程序文件」	文件夹没有完整复制过来，或者文件被删除	到 Releases 页面重新下载，解压后覆盖这个文件夹。通过「检查更新」升级会自动清理本平台的旧文件
环境变量删掉之后又出现	节点本身不稳定，监控按实际情况写入	正常现象。持续这样说明节点质量差，换一个
断开之后环境变量迟迟不删	软件的「断开」没有真正断开（内核还在运行），节点仍然可以连上	正常现象。想立刻停止就退出翻墙软件
状态里「终端同步」显示「装了但跑不起来」	Windows 执行策略不让 PowerShell 跑配置文件	按状态页第二行的提示改一次，改完重开一个窗口。只想让变量先生效的话，这一步可以暂时不管
上面都试过还不行	—	打开菜单选 2，把状态截图；再选 1 修复一次

大部分问题都可以用菜单的 选 1 解决。它不会重复安装，不会中断网络，也不会丢失你自己的设置。

5. 它是怎么判断在不在翻墙的

每 2 到 3 秒检查一次（翻墙时 2 秒，直连时 3 秒），但不会看到端口就认定。要同时满足三条：

有端口在监听 —— 本机有程序开了代理端口
它确实是代理 —— 发一次 CONNECT 握手，必须回 HTTP/1.x 200。这一步排除开发服务器和普通网页服务
它确实连得通外面 —— 通过这个端口访问 7 个不同的端点，任意一个真拿到响应就算通过

三条全过才写入变量。所以本机开着个网页服务不会被误判。

它不认品牌、不认进程名、不认端口号——那些只用来加快扫描，判断永远走这三条。

判「断开」比判「连上」谨慎得多：一次探测失败不算断开，要连续失败满 10 秒、至少 3 次才动手删变量；只要成功一次就立刻认作连上。因为误删变量的代价大，多等一会儿的代价小。下完结论后还会多盯 1 分钟，判错了能自己改回来。

操作	生效时间
打开翻墙软件	约 6–10 秒
完全退出翻墙软件	约 8 秒
只断开、没退出	约 15–50 秒
断线后重新连上	约 10–25 秒

写入哪些变量（翻墙时整套写，断开时整套删）：

变量	写入值	作用
`HTTP_PROXY`	`http://127.0.0.1:端口`	http:// 请求的代理
`HTTPS_PROXY`	`http://127.0.0.1:端口`	https:// 请求的代理
`ALL_PROXY`	`http://127.0.0.1:端口`	兜底，其他变量没覆盖的协议用它
`NO_PROXY`	`localhost,127.0.0.1,::1`	本机地址不走代理
`NODE_USE_ENV_PROXY`	`1`	让新版 Node 工具也读环境变量里的代理

Windows 写 5 个，macOS 写 9 个（同样 5 个，再加一份小写拼写）。Windows 变量名不区分大小写，写小写只会覆盖自己；macOS 区分大小写，有的工具只认小写。

这些设置为什么这样定（不影响使用，可以展开看）

代理值统一用 http://，不用 socks5://。本地代理端口两种协议都应答，部分工具只接受 http://，统一之后兼容面最大，没有损失。dsh 这类工具遇到 SOCKS 会警告并跳过。
Windows 不写两种拼写：两种拼写在那里是同一个变量，重复项会让 .NET 系宿主建表时报 An item with the same key has already been added，那个窗口里跑的所有程序都受影响。
NO_PROXY 里的 IPv6 要裸写 ::1。写成 [::1] 会被 httpx 当成普通域名，之后每次请求都报 InvalidURL。方括号是 URL 的写法，放错了位置。
你自己的 NO_PROXY 条目不会被删，只做补充；卸载时也只回收我们写入的值。
变量被别的程序改坏了不用管：监控每 30 轮核对整张表，缺了就补回来。
下面这些工具不读上面那 5 个变量，要单独配（不是本工具的问题）：

工具	配置位置
Maven	`settings.xml` 的 `<proxies>`
Gradle	`gradle.properties` 的 `systemProp.http(s).proxyHost/Port`
JDK 原生 HttpClient	JVM 系统属性（或 `java.net.useSystemProxies`）
Docker Desktop 的 `docker pull`	Docker Desktop 自己的设置（它忽略 `daemon.json` 里的代理）

NODE_USE_ENV_PROXY 只对新版 Node 生效：node:http(s) 要 22.21 / 24.5 以上，fetch() 要 22.21 / 24.0 以上。低版本设了没用，这是正常的。

6. 为什么它不容易出错

原则是：拿不准的时候不动。

读不出来就不动：端口列表读不出来时，它不会当成「没有代理」去删你的变量，而是沿用上一次的状态。
只清自己写下的值：你改过的手设值、公司代理、别的端口，一个都不动。没有归属记录时干脆不动。
改配置前先备份：Windows 的 $PROFILE、Mac 的 rc 文件，改写前都留一份 .envproxy.bak。写不进去就一字不改。
写文件保证完整：先写临时文件再整体替换。中途断电或被杀，原文件还是完整的。
重复装无害：已经装对了就不动你的设置，再跑一次也没问题。
卸载后会复查：逐项读回确认，有残留就报「未完成」，不会假装成功。

7. 性能与流量

稳定后开销很小：判断稳定之后，每个端口最多每 15 秒探测一次，只读取响应头，不读正文，每次不到 1KB。
收集证据时缩短间隔：出现失败但还没达到阈值时，改成 5 秒一次；结论刚翻转之后再快盯 60 秒（防止刚判完就反复翻），之后才回到 15 秒。
卸载后不留残留：环境变量、开机启动、定位脚本、终端同步脚本块全部清除，只保留你选择留下的日志。
终端提示符感觉不到延迟：每次显示提示符之前，只读一次本地状态（PowerShell 读注册表，Git Bash 读一个状态镜像文件，Mac 读 proxy.env），全程不启动任何外部进程。

8. 文件夹里都有什么

解压之后大体是这样。文件夹名可以改；每个包只有自己平台的目录，Windows 包里没有 mac\，反过来也一样。

EnvProxy\
  win\                     Windows 版
    打开菜单.cmd           Windows 上唯一需要双击的文件
    envproxy.ps1           主程序
    locator.ps1            定位脚本的源文件（安装时据它生成 %LOCALAPPDATA%\EnvProxy\launcher.ps1）
    lib\                   程序库（不用管）
    monitor\               运行时自动生成，放日志
  mac\                     Mac 版，结构一样
    打开菜单.command       Mac 上唯一需要双击的文件
    envproxy.sh            主程序
    locator.sh             定位脚本的源文件（对应 win 侧的 locator.ps1）
    prompt-sync.sh         终端同步脚本（给 zsh/bash 用）
    test-mac-pure.sh       自检脚本（self-test 用，随包发，不影响正常运行）
    lib\  monitor\         程序库；运行时自动生成，放日志
  README.md  README.en.md  中英文说明
  LICENSE  VERSION         许可证、版本号
  release-notes\          每版改了什么（选「检查更新」时显示）
  assets\readme\          README 的配图

两边一一对应，只有两个文件是 Mac 独有的：prompt-sync.sh 和 test-mac-pure.sh（Windows 的终端同步脚本由安装程序生成，不在文件夹里）。

分成三块，规矩不一样：

程序文件：win\、mac\、release-notes\、assets\。更新会覆盖，别往里放你自己的文件。
运行时目录：monitor\。日志和运行标记，永不覆盖、永不删除。
最外层：只覆盖同名文件，绝不删你的东西。

日常你只需要打开 win\（Mac 上是 mac\）。

安装之后，它往哪儿写了东西

都在这个文件夹之外，所以更新覆盖程序文件时碰不到它们：

位置	里面是什么	干什么的
`%LOCALAPPDATA%\EnvProxy\`	`launcher.ps1`	定位脚本，登录时用它找到程序
	`terminal.env`	给 Git Bash 看的镜像文件：当前状态和代理地址
`HKCU\Environment`	那 5 个代理变量	真正让终端走代理的地方
`HKCU\Software\EnvProxy`	`Owned`、`Backup` 两个键	记下我们写过哪些值、你原来的值是什么
`HKCU\...\Run`	一条启动项	登录时自动把后台程序拉起来
PowerShell 的配置文件	一小段（首尾有 `EnvProxy` 标记）	每次回到提示符时同步一次
`Git Bash 的 ~/.bashrc`	一小段（同样的标记）	Git Bash 每次回到提示符读镜像文件
`win\monitor\`	`monitor.log`、`monitor.pid`	它做过的判断、后台程序的进程号

卸载时上面这些全部清除，只保留你选择留下的 monitor.log。

9. 关于复制备份文件夹

可以复制、改名、搬走。 但要知道：原位置一改名或一搬走，正在跑的监控就找不到自己的程序了，它会自己退出并清掉代理变量（免得留下过期的设置）。

所以改名或搬家之后，让它回来有两种办法：

等下次登录：定位脚本会找到新位置并接管。
立刻回来：双击一次「安装 / 修复」。想省事就用这条。

搜索范围分两头：一是桌面、文档、下载、OneDrive、.config 这几个位置向下 6 层；二是其他磁盘的根目录向下 4 层（系统盘根不搜，免得全盘遍历）。所以 C:\Projects\EnvProxy 找不到，D:\Projects\EnvProxy 反而能找到。挪出这个范围，就得双击一次「安装」重新接管。

复制出来的备份不会被误认成正主（按日志活跃度判断哪份在跑），所以备份可以一直留着。

10. 给朋友/新电脑部署

把包弄到新机器上，两种都行：点 Windows 版下载，或者把整个文件夹拷过去（U 盘、网盘、压缩包都可以）
双击 win\打开菜单.cmd，选 1 安装 / 修复
好了。不需要管理员权限，不需要装别的东西

Windows 用户到这就完事了。两个平台各有各的包：Mac 用户下载 Mac 版，或者直接用包含 mac\ 的整个文件夹。

11. 技术边界（5 条）

边界	原因	影响
纯 TUN 模式不处理	不在本机开端口，没有端口可判断	流量本来就全经过它，不需要额外设置
不修改系统代理设置	那会影响浏览器和其他程序	只写入用户级环境变量，你随时可以在系统设置里确认没有被改动
不改变已经运行的程序	环境变量只在进程启动时读取一次	已经打开的窗口需要按一次回车（见第 0 节）
不管需要自己配置代理的工具	它们不读取这几个变量	Maven、Gradle、Docker 等见第 5 节的折叠表
不提供界面	零依赖是安装前提	只有一个菜单，没有托盘图标，没有窗口

纯 TUN 模式为什么真的不能碰：它和企业 VPN 无法区分，判断错了会删掉你唯一的代理路径，所以宁可不动。

Mac 侧多一条：launchctl 的环境变量在登录和重启时清空，所以监控每 30 轮核对一次，发现缺了就补回来（齐的时候不写）。

12. macOS 版

12.1 与 Windows 版的区别

Windows 写注册表并广播通知，Mac 写 ~/.envproxy/proxy.env 并调用 launchctl setenv。两条路径同时更新，看到的行为一致。

终端这边，Mac 的默认 shell 是 zsh（macOS 10.15 起），系统里也留着 bash 3.2。两个都支持：安装时往 .zshenv/.zshrc 和 .bash_profile/.bashrc 里各放一行，用哪种 shell 都会跟上。fish 不支持——它不读这些文件。

12.2 安装（3 步）

把 Mac 包（EnvProxy-mac.tar.gz）放到 Mac 上任意位置（或者把包含 mac\ 的整个文件夹复制过去：U 盘、隔空投送、压缩包都可以）
进入 mac 双击 打开菜单.command，选 1 安装 / 修复
看到「监控进程：已启动」就装好了

不需要 Homebrew、Python、Node，不需要 sudo，macOS 12 及以上自带的 zsh 就够。（只要 Mac 版：下载 EnvProxy-mac.tar.gz。）

12.3 菜单（与 Windows 一致）

菜单编号、行为、影响范围与 Windows 完全一致（包含 4 帮助、0 退出）。直接按回车等于查看状态。

12.4 `mac` 文件夹里都有什么

见第 8 节的文件夹结构。Windows 没有对应物的、Mac 独有的文件有两个：prompt-sync.sh（终端同步脚本，给 zsh/bash 用）和 test-mac-pure.sh（自检脚本）。

定位脚本两端各有一份源文件——Mac 是 locator.sh，Windows 是 win\locator.ps1。安装时据它生成真正会被登录拉起的那一份，放在固定位置（Windows 是 %LOCALAPPDATA%\EnvProxy\launcher.ps1）。

12.5 Mac 上首次安装可能遇到的三个问题

症状	原因	怎么办
双击没有反应，或提示「无法打开」	下载的文件被系统隔离	右键 → 打开；或在终端执行 `xattr -d com.apple.quarantine 打开菜单.command`
提示「权限不够」	脚本没有执行权限	在终端执行 `chmod +x 打开菜单.command`
安装完成但状态显示未运行	系统把后台项目拦住了，或者刚才那个「能不能访问文稿」点了不允许	后台项目：系统设置 → 通用 → 登录项与扩展，允许它运行。文稿权限：系统设置 → 隐私与安全性 → 文件与文件夹。改完再打开菜单选 1（安装 / 修复）一次

12.6 安装后多出哪些东西

安装会往三个地方写文件，都不是你下载的那个文件夹：

位置	里面的文件	干什么的
`~/.envproxy/`	`locator.sh`	定位脚本（告诉开机自启去哪儿找程序）
	`prompt-sync.sh`	终端同步脚本，rc 文件里只写一行引用它
	`path.conf`	记录项目文件夹现在在哪
	`proxy.env`	终端这一路的环境变量和当前状态
	`owned.env`	记录我们写入过的值，清除时只清这些（代理一次都没开过时不会有这份）
	`prev.env`	安装时保存的原始值，卸载时用来还原
	`monitor.stdout.log`	后台程序平时打印的东西（排查登录启动的问题看它）
	`monitor.stderr.log`	后台程序报的错
`~/Library/LaunchAgents/`	一个 `*.plist`	开机自启项，登录时把后台程序拉起来
项目文件夹的 `mac/monitor/`	`monitor.log`	它做过的判断（黑匣子）
	`monitor.pid`	后台程序的进程号

~/.zshrc、~/.bashrc 这类配置文件里也会多出一小段（首尾都有 EnvProxy 标记），删掉那一段等于关掉那个终端的自动跟随。

项目文件夹可以随便搬：下次登录会自动重新定位，备份文件夹不会被误选。卸载时上面这些全部清除，只保留你选择留下的 monitor.log。

12.7 给朋友/新 Mac 部署

把整个文件夹复制过去，进入 mac 双击 打开菜单.command，选 1 安装 / 修复，完成。

13. 许可证与问题反馈

MIT 许可证，可以自由使用和修改。

遇到问题请到 GitHub Issues 反馈。附上这几项可以省很多来回：

打开菜单选 2 查看状态 的截图
monitor\monitor.log 最后 20 行（Mac 是 mac/monitor/monitor.log）
你的系统版本，以及使用的翻墙软件名称

Name		Name	Last commit message	Last commit date
.github		.github
assets/readme		assets/readme
mac		mac
release-notes		release-notes
tests		tests
win		win
.gitattributes		.gitattributes
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.en.md		README.en.md
README.md		README.md
VERSION		VERSION

Latest commit

History

Folders and files

Repository files navigation