打开翻墙软件 = 终端自动翻墙；关掉 = 终端自动恢复直连。全程零操作、零残留、零管理员权限。
- 一句话说明它是干什么的
- 一、安装（3 步，5 分钟）
- 二、五个按钮的确切行为（小白必读）
- 二点五、关于日志（monitor.log）
- 三、日常使用（装完后什么都不用做）
- 四、它是怎么判断"在不在翻墙"的（大白话）
- 五、保护机制（为什么它"稳"）
- 六、故障排查
- 七、性能与流量
- 八、文件夹里都有什么
- 九、关于复制备份文件夹
- 十、给朋友/新电脑部署
- 十一、诚实的技术边界（4 条）
- 十二、macOS 版（与 Windows 版行为一致，文件并排共存）
- 十三、许可证与问题反馈
你的翻墙软件（MonoCloud、Clash、v2rayN、Hiddify……任何带本地代理端口的）能让浏览器翻墙，但命令行工具（OpenCode、git、npm、curl 等）根本不理它——因为这些工具只认"环境变量"。
EnvProxy 就是那个翻译官：它盯着"翻墙软件到底有没有在翻墙"，翻着就把代理写进环境变量，不翻了就删掉。你什么都不用管。
注意：它只管环境变量（命令行工具的世界），从来不碰系统代理（浏览器的世界）。两个世界互不打扰。
TUN 用户先看一眼：如果你开的是 TUN 模式，流量已经被全局接管，终端本来就能翻墙——不需要本工具（预期行为，见第十一节第 1 条）。
翻墙时整套写入、断开时整套删除，同进同退：
| 变量 | 写入值 | 作用 |
|---|---|---|
HTTP_PROXY / http_proxy |
http://127.0.0.1:端口 |
http:// 请求的代理 |
HTTPS_PROXY / https_proxy |
http://127.0.0.1:端口 |
https:// 请求的代理 |
ALL_PROXY / all_proxy |
http://127.0.0.1:端口 |
兜底变量：具体变量没覆盖到的协议用它 |
NO_PROXY / no_proxy |
localhost,127.0.0.1,::1 |
本机地址不走代理（直连） |
NODE_USE_ENV_PROXY |
1 |
让新版 Node 系工具（原生 fetch）也读环境变量代理 |
写法说明：所有代理值统一用
http://协议（而不是旧的ALL_PROXY=socks5://）。本地代理端口（MonoCloud/Clash 等）都是混合端口，HTTP 和 SOCKS5 都能应答；但部分工具只认http://、不支持socks5://（例如 dsh 会打印"all_proxy names a SOCKS proxy, which is not supported"警告并跳过）。统一http://对所有工具的兼容面最大，行为没有任何损失。
- 把整个
EnvProxy文件夹放到你喜欢的位置（任何位置、任何名字都行） - 进
win文件夹，双击1-安装.cmd - 看到"监控进程已启动"即完成
装完它做了三件事：
- 把监控程序注册为开机自启动（以后开机自动干活，不用再点）
- 立即启动监控
- 当场校正一次环境变量（该注入注入、该清理清理）
以后想升到新版：进
win文件夹，双击5-检查更新.cmd（先告诉你最新版，问过你才装；日志原样保留）。遇到任何不对劲要修复：进
win文件夹，直接再双击一次1-安装.cmd就行，它是"万能修复按钮"，不会重复安装、不会断网、不会丢东西。
五个按钮都在
win文件夹里：在下面说"双击"时，都是指进win文件夹双击。
| 按钮 | 干了什么 | 留下的东西 | 什么时候用 |
|---|---|---|---|
| 1-安装 | 开机自启动 + 启动监控 + 校正变量 | 全部就位 | 首次安装 / 任何时候"不对劲"了点它 |
| 2-停止监控 | 停掉监控进程 + 删除环境变量（立即恢复直连） | 保留自启动 + 定位器 + 路径记录（下次开机自动恢复监控） | 想临时停用，下次开机还要 |
| 3-一键恢复 | 停监控 + 删环境变量 + 删自启动 + 删定位器 + 删路径记录 | 日志去留由你当场选择（默认保留） | 彻底不想要这个功能了 |
| 4-查看状态 | 显示监控/自启动/翻墙状态/变量/版本/最近日志 | — | 想看它工作得怎么样 |
| 5-检查更新 | 查 GitHub 最新版 → 问过你才装（整包覆盖，不断网、不丢日志） | 版本号更新，其余就位 | 有新版想升级 |
一句话记忆：
- 2-停止 = 暂停（下次开机自己回来）
- 3-一键恢复 = 卸载，问你一句"日志留不留"
- 1-安装 = 万能修复（无论什么问题，点它）
- 5-检查更新 = 升级（先问你，点了头才装）
双击"3-一键恢复"时会停下来问你：历史日志保留吗？回车 = 保留（黑匣子）；输入
N回车 = 连日志一起删。二选一，没有多余按钮。补充：所有按钮都不会自动删除
EnvProxy文件夹本身（卸载后系统里不留任何痕迹，但文件夹和脚本还在原地，方便你日后想重新安装，或手动删掉整个文件夹即可）。
- 它只记录"状态变化"（启动/退出/注入/删除/异常），稳定运行时不写任何东西
- 体积有硬上限 200KB：超过自动截断为最近 200 行——用几年也不会越写越大
- 它就是你的黑匣子：日后任何"咦，当时发生了什么"的问题，看它就知道
- 一键恢复时会问你留不留：回车 = 留；输入
N= 删
| 你的操作 | 自动发生什么 | 大约耗时 |
|---|---|---|
| 打开翻墙软件连接 | 检测到翻墙 → 写入环境变量 | ~4-10 秒 |
| 断开/退出翻墙软件 | 检测到没翻墙 → 删除环境变量 | 退出软件约 8 秒；断开连接 ≤35 秒 |
| 改任意端口后重连 | 自动发现新端口 → 更新为新值 | ~10 秒 |
| 换一个翻墙软件 | 自动发现新软件的端口 | 秒级~几秒 |
| 同时开两个翻墙软件 | 只用验活的那一个（按端口表顺序优先），前一个断了自动让位 | 零操作 |
| 几秒内反复连接/断开 | 防抖机制吸收，变量纹丝不动 | — |
| 重启电脑（关机前没退翻墙软件） | 开机立即校正残留变量 | 零操作 |
| 把整个文件夹移到别处（任何时候，含监控运行中） | 旧监控 2-3 秒自动退出并清干净旧位置；重启自动从新位置启动 | 零操作 |
每 2-3 秒看一眼：本机有没有代理端口在"开门营业"？
↓ 有端口在听
再问一句：这个端口会回答代理的握手吗？（CONNECT 探测）
↓ 会
再真刀真枪试一次：通过它访问一次外网通不通？（真实节点验证）
↓ 通 = 真在翻墙 → 写环境变量
↓ 不通（比如断开连接但软件内核还活着）→ 删环境变量
三层验证，缺一不可。所以它不会被"假代理"骗、不会把"断开的软件"当翻墙、也不会漏掉"换了端口"的新软件。
为什么找到任何翻墙软件都能用：它不认品牌、不认进程名、不认端口号——只认"谁真的在提供代理服务"。市面上所有带本地代理端口的翻墙软件（Clash 全家、v2rayN、Shadowsocks、Hiddify、sing-box、NekoBox、Surge……）全都适用。
| 机制 | 作用 |
|---|---|
| 双轮确认（去抖） | 状态连续确认 2 轮才动手——几秒内反复连接断开，变量一次都不乱写 |
| 节点迟滞 | 连续 2 次探测失败才判"断"——节点偶尔抖动不会误删 |
| 多端点验证 | 7 个连通性检查端点跨厂商/跨域段（Google 主域 / gstatic / YouTube / Wikipedia / Twitter）；快路优先：正常只测"上次成功的端点"（毫秒级、1 个请求），它失败才并行兜底其余端点，任一成功即判"通"并自动学习为新快路——单个域段（如 Google 主域）被干扰/慢速时其余域段照样兜底，杜绝误删 |
| 探测节流 | 真实探测 15 秒最多一次——每次不足 1KB（24 小时翻墙也就几 MB 上限，只在翻墙时产生） |
| 启动对齐 | 开机立即校正变量——关机残留死端口瞬间清掉 |
| 监控自退 | 文件夹被移动/删除 → 监控 2-3 秒发现并自动退出，旧位置清理干净 |
| 定位器兜底清理 | 移动后立刻关机（监控来不及自退）→ 下次开机定位器顺手清掉旧位置残留 |
| 活跃度优先定位 | 定位器搜索按"最近在用的"选——你复制的备份文件夹永远不会被误选 |
| 跨位置优雅停止 | 停止旧位置监控时把信号写到"它自己"的目录，优雅退出而非强杀 |
| 共享文件流 | 日志写入零锁冲突，监控自身截断永不撞锁 |
| 自启动自愈 | 每 60 秒自查，定位器/自启动项损坏自动重建 |
| 单实例锁 | 永远只有一个监控进程，不会越积越多 |
| 快路径握手门 | 已知端口光在监听不够，还要 CONNECT 握手通过才算候选——本机开发服务器（常占 8080/8888）不会被误判为代理 |
| 在位复核 | 已锁定的端口约每 10 轮补一次本机握手（零流量）；代理退出后若有别的程序占了同一端口，立即丢缓存、不等节点节流 |
| 集合试活 | 候选排好队逐个验活，上次验活的优先认回；双开时前死后活自动让位，稳态不烧新探测 |
| 现象 | 原因 | 解决 |
|---|---|---|
| 装好后终端还是不能翻墙 | 终端是装之前开的旧窗口 | 彻底关掉重开一个 |
| 断开连接后变量迟迟不删 | 你的软件"断开"没真断（内核还活着），或节点还在通 | 正常现象；想立即停止请退出翻墙软件 |
| 变量偶尔删了又恢复（反复横跳） | 你的节点本身在抖动（时通时断），监控如实反映 | 已有多端点验证兜底；若持续，说明节点质量差，换节点即可 |
| 明明连着翻墙软件却显示"变量已删除" | 节点对验证端点所在的域段暂时不通（如 Google 主域被 DNS 污染/线路问题），而验证端点全是该域段 → 误判"断" | 新版本已把验证端点扩为 7 个跨域段（快路优先 + 失败并行兜底），此问题根治；遇到旧版本请进 win 重新双击一次"安装"更新 |
| 显示"检测异常"日志 | 单轮检测出错（不影响整体） | 不用管，会自动恢复；持续出现就点一次"安装" |
| 安装时报一堆"意外的标记 ) / }"（语法错误） | 脚本文件编码损坏：PowerShell 5.1 在非 UTF-8 代码页的系统上按 ANSI 读取无 BOM 的脚本 → 中文乱码撑破语法结构 | 本版本已内置 UTF-8 BOM 根治（任何系统直接可用）；若仍报错说明文件被文本工具重存过，重新拷贝一份官方文件夹覆盖即可 |
| 翻墙软件换了极深的目录（D:\a\b\c\d\e\f） | 自动搜索覆盖不到 | 进 win 双击一次"安装" |
| 检查更新时显示"检查失败" | 本机网络暂时到不了 GitHub（或 API 限流） | 稍后重试；翻墙开/关换个状态再试一次也常有效 |
| 更新中途报错 | 下载/解压/校验失败 | 旧版未被破坏，重跑一次 5-检查更新 即可 |
| 给本地代理加了认证（用户名密码） | 无认证的握手被回 407，判"不可用"是保守正确 | 关掉本地认证（默认都是关的），或换无需认证的本地端口 |
| WSL2 里面的终端不生效 | WSL2 默认不继承 Windows 的用户环境变量 | 预期行为：在 WSL 里另行设置代理变量 |
| 管理员终端（提权运行）不生效 | 提权进程属于另一个管理员身份，不继承你当前用户的变量 | 预期行为：用普通（非提权）终端 |
| 想彻底回到没装之前 | — | 进 win 双击"3-一键恢复"，日志留不留当场选 |
以下数字因机器而异，给的是量级和口径，不保证你机器上一字不差——任务管理器里找命令行带 envproxy.ps1 的 powershell 进程，看一眼即知。
- CPU：平时基本看不见。探测逻辑每轮毫秒级，开销主要是一个 PowerShell 进程的底座；本机（16 核）30 秒窗口实测约 0.003%，核越少占比越高
- 内存：几十 MB 量级，同样是进程底座为主（本机实测工作集约 48MB）；Mac 那边是 bash，没有这个量级的运行时
- 流量：真实节点探测正常只测 1 个端点（每次不足 1KB）、15 秒最多一次；仅当该端点异常时才并行兜底其余端点（短暂、罕见）。24 小时翻墙也就几 MB 上限；完全不翻墙 = 零流量（off 状态只有本机端口扫描，不出外网）
- 写操作：只在状态变化时写一次（幂等），稳定时日志一个字都不写
EnvProxy\
win\ Windows 版（5 个按钮 + 核心脚本，Mac 用户不用看）
1-安装.cmd 安装（万能修复）
2-停止监控.cmd 暂停（保留自启动）
3-一键恢复.cmd 卸载（日志去留当场选）
4-查看状态.cmd 查看状态（含版本信息）
5-检查更新.cmd 检查更新（一键升级，问过才装）
envproxy.ps1 核心脚本（所有逻辑）
monitor\ 运行时文件夹（自动生成；卸载时日志按你的选择保留或删除）
monitor.log 黑匣子日志（只记状态变化，200KB 上限自动截断）
monitor.pid 运行标记
stop.flag 停止信号（临时文件，用后即删）
mac\ Mac 版（结构与 win\ 对称，见第十二节 12.4）
README.md 本文档（中文，权威）
README.en.md 英文版（与本文同步）
日常使用只进
win（或 Mac 上只进mac），根目录的文档不用动。
可以把整个 EnvProxy 文件夹复制到别处当备份，完全无害：
- 开机自启动、注册表、定位器只引用你安装过的那个文件夹，备份不会被引用
- 即使原文件夹被移动，定位器重新搜索时也按活跃度排序——最近在用的（有日志活动的）优先，备份永远不会被误选
- 唯一注意：不要在备份文件夹里双击"
win\1-安装.cmd"（点了就等于把备份切换为正式项目） - 同一台电脑只保留一份安装：搬家前先到旧位置点一次"3-一键恢复"，再到新位置点"安装"，避免两个监控同时写同一组变量
- 把代码弄到新电脑（二选一）：
git clone https://github.com/FiretrUCK666/envproxy.git（推荐）；或整文件夹拷贝（用 U 盘/网盘/压缩包都行，别用文本编辑器另存过里面的 .ps1 文件——会破坏 UTF-8 BOM 编码） - 双击
win\1-安装.cmd - 完事
以后更新：进 win 文件夹双击 5-检查更新.cmd，问过你之后一键升到最新版（整包覆盖，不漏文件；日志原样保留）。
用 git clone 装的也可以 git pull 拉到最新后，进 win 文件夹再双击一次 1-安装.cmd（等效备用：加载新代码并校正一次变量）。
编码说明：
win\envproxy.ps1/ 日志采用 UTF-8 BOM 编码，为的是在任何中文/英文系统的 Windows 上都能被 PowerShell 5.1 正确读取（无 BOM 时中文系统会按 GBK 读、英文系统按 Latin1 读，都可能报语法错误或乱码）。如果你日后用编辑器修改过win\envproxy.ps1，保存时务必保留 UTF-8 BOM（VS Code / Notepad++ / 记事本选"UTF-8 with BOM"），改完顺手进win双击一次"安装"让监控加载新代码。
不需要装任何东西（Node/Python 都不需要），不需要管理员权限，Windows 10/11 自带 PowerShell 即可。
- 纯 TUN 模式的翻墙软件（不开本地 HTTP 端口）：TUN 本身已经全局接管（终端自动翻墙），本工具检测不到端口 → 不注入 → 这是正确行为，不需要它。Outline 这类系统级 VPN、纯 SOCKS（无 HTTP 口）同理：没有本地 HTTP 端口就永远发现不了，不是 bug。
- "断开连接"≠ 退出软件：多数翻墙软件的"断开"按钮不停内核，端口还活着。本工具以"流量真相"为准：翻得出去就注入，翻不出去才删除。
- 搬家到极深层目录（超过搜索深度）：搜索不到时进
win双击一次"安装"兜底，其余场景全自动。 - 此前手设过的代理会被接管：如果你以前手动设过系统/用户代理变量，安装会覆盖它们，卸载会删掉且不恢复原值（个人电脑极少有这种情况；公司内网机先记下原值再装）。
Windows 用户看到这里就可以停了。下面只讲苹果电脑。Windows 文件在
win\，Mac 文件在mac\，两套并排，整文件夹拷贝到 Mac 就能用。
Windows 版把变量写进注册表、广播一次就全局生效；macOS 没有注册表，所以 Mac 版双路同时写：终端走 ~/.envproxy/proxy.env（新开终端自动加载），Dock 启动的 App 走 launchctl setenv。两路同进同退，你感知不到区别。
Mac 版注入的也是整套 9 个变量（HTTP_PROXY/http_proxy/HTTPS_PROXY/https_proxy/ALL_PROXY/all_proxy 统一 http://127.0.0.1:端口，NO_PROXY/no_proxy=localhost,127.0.0.1,::1，NODE_USE_ENV_PROXY=1），逻辑参数与 Windows 一致：2 秒/3 秒轮询、双轮确认、连续 2 次失败才判断、7 端点快路+并行兜底、15 秒节流、日志 200KB 上限、60 秒自启自愈。
- 把整个
EnvProxy文件夹拷到 Mac 上任意位置（U 盘/隔空投送/压缩包都行） - 进
mac文件夹，双击1-安装.command（首次可能要右键→打开放行一次，见 12.5） - 看到"监控进程已启动"即完成；新开一个终端验证：
env | grep -i proxy
装完同样是三件事：开机自启（LaunchAgent）+ 立即启动监控 + 当场校正一次变量。以后任何不对劲，进 mac 双击一次 1-安装.command 就是万能修复。
fish 用户注意：fish 读不懂
proxy.env的 export 写法，需装 bass 后在config.fish加一行bass source "$HOME/.envproxy/proxy.env"。
五个按钮都在
mac文件夹里：在下面说"双击"时，都是指进mac文件夹双击。
| 按钮 | 干了什么 |
|---|---|
| 1-安装.command | 开机自启 + 启动监控 + 校正变量（万能修复） |
| 2-停止监控.command | 停监控 + 删变量（保留自启动，下次登录回来） |
| 3-一键恢复.command | 停监控 + 删变量 + 删自启动/定位器/hook，日志去留当场问 |
| 4-查看状态.command | 监控/自启动/翻墙状态/变量/版本/最近日志 |
| 5-检查更新.command | 查最新版 + 问过才装（一键升级） |
终端用户也可以（在项目根目录）：bash mac/install.sh / bash mac/stop.sh / bash mac/uninstall.sh（加 --purge 连日志一起删）/ bash mac/status.sh。.command 只是"双击壳"，逻辑全在 .sh 里。
EnvProxy/
mac/
envproxy.sh Mac 核心（对标 win\envproxy.ps1，单文件、只用系统自带命令）
locator.sh 定位器模板（安装时复制到 ~/.envproxy/locator.sh）
install.sh / stop.sh / uninstall.sh / status.sh / update.sh
1-安装.command … 5-检查更新.command（双击入口）
monitor/ 复用（monitor.log / monitor.pid / stop.flag，格式不变）
~/.envproxy/ 是固定位置（locator.sh + path.conf 路径记录 + proxy.env），项目文件夹随便搬家，下次登录自动重新定位。备份文件夹随便复制，不会被误选（按日志活跃度排序）。
- 双击没反应 / 提示"无法打开"：这是 Gatekeeper。解法三选一：右键→打开放行一次；或终端跑
bash mac/install.sh（永远有效）；或xattr -d com.apple.quarantine mac/1-安装.command后再双击。 chmod权限丢了（从 Windows 拷过来常见）：终端进mac目录跑一次chmod +x *.command *.sh即可。- 首次登录弹"终端想访问文稿/桌面"：点"好"即可（定位器要搜索新位置）。点了"不允许"也不坏：手动双击一次安装就纠正了。
照搬：纯 TUN 不注入（正确行为）；"断开≠退出"以流量真相为准；极深目录双击安装兜底。
新增：
- 旧终端必须重开（与 Windows 一致）：已开的窗口不变，只有新开的终端/App 才生效。
- core 语言是 shell 不是 python：Mac 自带的
/usr/bin/python3是 Xcode 附带的旧版本，新系统缺组件会直接报错，所以 Mac 版故意只用zsh/bash/curl/lsof/launchctl（全是出厂自带），真正零依赖。改完mac/envproxy.sh保存为 LF、无 BOM（与 Windows 的 UTF-8 BOM 相反，带 BOM 会顶掉 shebang 导致无法执行）。
整文件夹拷贝 → 进 mac 双击 1-安装.command → 完事。不需要 Homebrew/Python/Node，不需要 sudo，macOS 12+ 默认 zsh 即可。
想升级：进 mac 双击 5-检查更新.command（先问后装，日志保留）。
本项目以 MIT 许可证开源（见 LICENSE）：可以随便用、随便改、随便分发，保留版权声明即可。
想贡献代码（报缺陷、提改动）先看 CONTRIBUTING.md（提问格式、fork 流程、提交前门禁），直接改完就提 PR 会被打回。
遇到问题先看第六节故障排查；解决不了到仓库 Issues 区提问：https://github.com/FiretrUCK666/envproxy/issues。提问时附上：你的系统版本、win\4-查看状态 的完整输出、win\monitor\monitor.log 最近的相关行（Mac 用户对应 mac 下同名文件）。想自己改代码先看 CONTRIBUTING.md。