分类
技术

终端代理总是失效?用 NetFerry 统一 git、pip 和 Codex 的网络出口

NetFerry 是一个本地自适应出口网关:优先直连,失败自动回退到代理,让终端里的 git、pip、npm 和 Codex 不再为代理设置发愁。

平时开着代理软件,浏览器访问外网一切正常。但一回到终端,问题就来了:

git clone https://github.com/xxx/xxx.git
pip install requests
npm install

这些命令经常超时或者直接报网络错误。原因并不复杂:代理软件里的“系统代理”主要影响读取 Windows 系统代理设置的程序,比如浏览器;而终端里的 git、pip、npm 等工具,看的是环境变量:

HTTP_PROXY
HTTPS_PROXY
ALL_PROXY

于是每次开终端都要手动设置:

$env:HTTP_PROXY = "http://127.0.0.1:7897"
$env:HTTPS_PROXY = "http://127.0.0.1:7897"

还衍生出一堆麻烦:

  • 每开一个新终端都要重新设置。
  • 用 `git config –global http.proxy` 之后,关掉代理又得记得手动取消。
  • 用 Codex、Claude Code 这类工具时,经常要专门提醒 AI:“git push 要走代理端口”“现在没开代理,不要走代理”。
  • 有些地址明明可以直连,却因为全局代理被绕了一圈,速度反而更慢。

这些问题的本质是:终端里的代理设置是静态的,而网络可达性是动态的。

思路:把路由决策放到本地网关

NetFerry 做的事情很简单:在本地启动一个 HTTP 代理网关,默认监听:

127.0.0.1:17890

然后把终端里的代理变量统一指向它。之后不再由每个工具、每次命令去判断“该不该走代理”,而是由 NetFerry 统一决定:

终端命令
  -> HTTP_PROXY / HTTPS_PROXY
  -> NetFerry 本地网关 127.0.0.1:17890
       -> 目标可直连:直接连接
       -> 直连失败:回退到上游代理

具体行为:

  • 请求到达网关后,先探测目标是否可以直连。
  • 能直连就直连,不经过代理。
  • 直连失败才回退到配置的上游代理。
  • 路由结果按目标主机缓存,避免每次都重复探测。
  • 上游代理没开时,直连可达的网站仍然能正常访问。

对使用者的意义是:终端里只需要认一个固定地址 127.0.0.1:17890,不用再关心今天开没开代理、哪个端口、哪些域名该走哪条路。

安装

项目地址:

当前版本是 `v0.3.3`。Windows 下载 `.zip`,Linux/macOS 下载 `.tar.gz`,Release 页面里有各平台的版本选择说明。

安装前只需要做一件事:先启动代理软件。代理软件里的系统代理开关可以保持关闭,NetFerry 会直接探测本地监听端口。

Windows:

1. 解压 `netferry-windows-amd64.zip` 到固定目录,例如 `C:\Tools\NetFerry`。不要留在 Downloads,否则以后删除解压目录会导致自启动失效。

2. 双击 `install.bat`。

3. 确认检测到的代理后输入 `Y`。出现SUCCESS即为安装成功。

Linux / macOS:

tar -xzf netferry-linux-amd64.tar.gz
cd netferry-linux-amd64
chmod +x netferry
./install.sh

Linux 需要可用的 systemd 用户会话,macOS 需要已登录的 GUI 会话;WSL、容器或只有 SSH 的环境请加 `–no-service`。

安装程序会自动探测本地代理端口。常见的 v2rayN、Clash、Mihomo、sing-box 等端口都在探测范围内;也会读取系统代理设置和 `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` 环境变量。

如果检测不到,可以手动指定:

.\netferry.exe setup --upstream http://127.0.0.1:10808

配置保存在:

%APPDATA%\netferry\netferry.toml

NetFerry 不会自动把程序目录加入 PATH。如果不在程序目录,使用完整路径即可。

之后需要换端口,不需要手改文件:

.\netferry.exe config set upstream http://127.0.0.1:7897

安装完成后,重启终端、Codex、IDE 等需要继承新环境变量的程序。已经打开的终端不会自动获得新变量。

日常使用

安装完成后,按平常习惯执行命令即可:

git clone https://github.com/example/project.git
pip install requests
npm install
gh repo view

不需要再设置 git config --global http.proxy,也不需要每次打开终端手动 set HTTP_PROXY。Codex、Claude Code 等工具从终端继承环境变量后,执行 `git push`、包管理等命令也会自动经过 NetFerry。

如果只想临时执行一条命令,不想安装持久环境,也可以用:

.\netferry.exe run -- git clone https://github.com/example/project.git

run 会在需要时临时启动网关,只给这条子命令注入代理变量,命令结束后关闭网关。

几个常见问题

检测不到本地代理

先确认代理软件已经启动,并且本地端口处于监听状态。仍然检测不到时,用 `–upstream` 手动指定:

.\netferry.exe setup --upstream socks5h://127.0.0.1:10808

新终端里没有代理变量

安装前已经打开的终端不会自动更新环境。新开一个终端,或者注销并重新登录一次。

管理员禁用了注册表编辑

部分受管电脑会禁用 regedit / reg.exe。NetFerry 会优先尝试 `HKCU\…\Run`,如果被拒绝,会自动回退到启动文件夹:

%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\NetFerry.cmd

不需要管理员权限;如果启动失败,可以查看 %APPDATA%\netferry\netferry.log。

git@github.com:... 这类 SSH 地址

SSH 不读取 HTTP_PROXY。NetFerry 目前解决的是使用 HTTP/HTTPS 代理的工具;SSH 的 ProxyCommand 支持还在路线图中。

普通 http:// 请求

NetFerry 当前主要处理 HTTPS 使用的 CONNECT 隧道。依赖 CONNECT 的 git、pip、npm 等工具可以正常工作;普通明文 HTTP 转发还在后续计划中。

边界

NetFerry 不是 VPN,也不是透明代理:

  • 只对支持标准代理环境变量的程序生效。
  • 不会解密 HTTPS。
  • 不会接管完全忽略代理变量的程序。
  • PAC / 自动代理脚本不会被执行。

它解决的是一个很具体的问题:让终端和 Agent 始终使用同一个本地入口,由这个入口决定直连还是回退代理。

如果你也经常在“开代理 / 关代理”“直连 / 走代理”之间来回折腾,可以试试这个工具。项目还在早期阶段,欢迎在 GitHub 提 Issue 或 PR。

– 项目主页:https://github.com/coni233/netferry

– 下载安装:https://github.com/coni233/netferry/releases

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注

在此处输入验证码 : *

Reload Image