Geph 免费版 + iTerm：给 macOS 终端补一层可用的外网代理

2026-11-01T00:00:00+00:00

Geph 免费版 + iTerm：给 macOS 终端补一层可用的外网代理

TL;DR：Geph 在 macOS 上可以开启本机 HTTP/SOCKS5 代理。本文用 geph_proxy.zsh 把 iTerm 里的 curl、git、Homebrew 等终端工具的流量接到 Geph，同时在 NO_PROXY 中排除常见国内域名。脚本会先核对 9910/9909 端口，再实际访问国外测试站；只有验证成功才设置代理变量，失败则自动清理。

Geph 官方入口：Geph 官网 · Geph 官方文档 · Geph 官方 GitHub。请从官网下载客户端，并遵守所在地区法律法规及 Geph 服务条款。

1. 目标与适用边界

本方案只解决一个具体问题：让 macOS 终端获得镜像站没有覆盖的外网访问能力。

它适合：

curl、wget、git clone/fetch/pull 等会读取代理环境变量的命令行工具；
Homebrew、npm、pip、Go 等能够继承 HTTP_PROXY / HTTPS_PROXY 的终端程序；
已有的 GitHub、Homebrew、PyPI 镜像没有覆盖的国外域名；
希望把 Geph 放在后台，只给终端提供按需代理的 Mac 用户。

它不适合：

浏览器、App Store、原生桌面应用等不读取 zsh 环境变量的程序；
ping、普通 UDP、git@github.com: 形式且未配置 ProxyCommand 的 SSH 连接；
需要完整 TUN 或系统级 VPN 的场景。

镜像站和 Geph 是互补关系。GitHub、Homebrew、PyPI 等已有国内镜像的下载仍应优先走镜像；Geph 只弥补镜像没有覆盖的域名。把大文件也强行送进免费代理，只会更慢。

2. 实测环境

项目	本文检查值	说明
macOS	27.2 / arm64	Intel Mac 的安装路径与终端用法相同
Shell	zsh 5.9	依赖交互式 zsh 加载 `~/.zshrc`
Geph	5.9.1	其他 5.x 版本请核对设置页
Geph HTTP 代理	`127.0.0.1:9910`	优先使用，兼容性最好
Geph SOCKS5 代理	`127.0.0.1:9909`	HTTP 端口不可用时自动尝试
脚本	`geph_proxy.zsh`	完整源码，建议下载后先阅读再加载

端口必须与 Geph 设置页完全一致。默认约定是 HTTP 9910、SOCKS5 9909；如果把 Geph 改成其他端口，就要同步修改脚本顶部的 GEPH_HTTP_PORT、GEPH_SOCKS_PORT，或者把 Geph 改回默认端口。不要把两个端口写反。

3. 安装并配置 Geph

3.1 安装客户端

从 Geph 官网下载 macOS 版本，按官方提示完成安装并启动。第一次使用时按客户端要求创建或登录免费账户。

免费版的速度会受限。Geph 5.9.1 的界面提示免费账号限速，因此它更适合网页访问、API、代码拉取和小文件下载，不适合把几十 GB 的镜像下载全部塞进代理。

3.2 开启本地代理

在 Geph 中进入：

设置 → 局域网 → 本地代理

确认：

“本地代理”处于开启状态；
“SOCKS5 端口”为 9909；
“HTTP 代理端口”为 9910；
Geph 已连接；
至少有一个可用节点。

“自动配置代理”会尝试修改系统代理。本文的脚本只改当前 iTerm 环境，不依赖系统代理是否开启，因此不会强制浏览器走 Geph。

3.3 先验证端口

安装好本文脚本后，可以直接运行：

geph_proxy ports

也可以手动检查：

lsof -nP -iTCP:9909 -iTCP:9910 -sTCP:LISTEN

预期可以看到 Geph 进程监听这两个端口。如果只有 5678 这类本地控制界面端口，没有 9909/9910，说明 Geph 的本地代理没有真正启动；此时继续配置代理环境变量只会得到 Proxy CONNECT aborted 或连接拒绝。

如果设置页已经显示“本地代理开启”，但 9909/9910 仍未监听，先将 Geph 完全退出，再从 Finder 或 Dock 正常启动；或者关闭“本地代理”后重新开启。仍无效时，再检查 Geph 版本和官方文档。

4. 阅读、下载并加载终端脚本

4.1 先阅读源码，再下载

脚本会修改当前终端的代理环境变量，并可能尝试启动 Geph。建议先打开 geph_proxy.zsh 完整源码阅读，确认端口、代理变量、启动命令和清理逻辑符合你的预期，再保存到本机。

为了便于说明，下文的示例目录是：

~/.local/share/geph-proxy/

这只是示例，你可以把脚本放到自己的任意目录；后续所有 source 命令都要使用实际路径。

浏览器下载时，选择“文件 → 存储为”，把文件保存为：

~/.local/share/geph-proxy/geph_proxy.zsh

下载后确认文件可读，并再次查看内容：

test -r "$HOME/.local/share/geph-proxy/geph_proxy.zsh" \
  && echo "geph_proxy.zsh 已就绪"
less "$HOME/.local/share/geph-proxy/geph_proxy.zsh"

4.2 加入你自己的 `~/.zshrc`

先备份现有的 zsh 配置：

cp "$HOME/.zshrc" "$HOME/.zshrc.backup.$(date +%Y%m%d-%H%M%S)"

然后用编辑器打开自己的 ~/.zshrc，在末尾加入：

# Geph terminal proxy
source "$HOME/.local/share/geph-proxy/geph_proxy.zsh"

示例路径 ~/.local/share/geph-proxy/geph_proxy.zsh 必须与你实际保存脚本的位置一致。不需要 source 整个函数目录；只 source 这一个文件即可。

保存后，可以重新打开 iTerm，或者在当前终端立即加载配置：

source "$HOME/.zshrc"

4.3 应用后的基础测试

先确认 zsh 已经识别 geph_proxy 函数：

whence -w geph_proxy

正常输出类似：

geph_proxy: function

然后按顺序测试：

geph_proxy ports
geph_proxy on --quick
geph_proxy status
geph_proxy off

四步分别用于检查 Geph 端口、验证代理能否访问外网、确认当前终端变量、清理当前终端代理。如果 whence -w 找不到函数，先检查脚本路径，再确认 ~/.zshrc 中的 source 行没有写错。

本文故意使用 geph_proxy 作为主命令，避免与已有的 proxy 函数互相覆盖。如果你更喜欢短命令，可以在确认没有同名函数后自行添加别名：
alias proxy='geph_proxy on'
alias unproxy='geph_proxy off'

5. 使用方式

5.1 开启、验证并测速

geph_proxy on

它会依次执行：

测试 Geph HTTP 127.0.0.1:9910；
HTTP 不行时测试 SOCKS5 127.0.0.1:9909；
两个端口都未开放时尝试启动 Geph 并等待；
通过候选代理访问国外 HTTPS 测试站；
只有外网访问成功才设置终端代理变量；
默认下载约 10 MB 数据，显示 Mbps、MB/s 和首字节延迟。

开启后，当前终端启动的子进程会继承这些变量：

http_proxy
https_proxy
all_proxy
no_proxy
HTTP_PROXY
HTTPS_PROXY
ALL_PROXY
NO_PROXY

5.2 只验证外网，不下载测速

geph_proxy on --quick

这个模式仍会测试代理能否访问国外站点，只跳过 10 MB 下载测速，适合频繁切换终端或流量有限时使用。

5.3 查看状态

geph_proxy status

5.4 重新测速

geph_proxy test

5.5 检查端口

geph_proxy ports

5.6 关闭代理

geph_proxy off

关闭只清理当前终端的环境变量，不会退出 Geph，也不会改变 Geph 的节点或系统 VPN 状态。

5.7 命令速查

命令	作用
`geph_proxy on`	自动选择 Geph 端口、验证外网并测速
`geph_proxy on --quick`	验证外网，不下载测速
`geph_proxy off`	清除当前终端代理变量
`geph_proxy test`	重新验证并测速
`geph_proxy status`	查看当前代理和八个环境变量
`geph_proxy ports`	检查 `9910/9909` 是否真正监听
`geph_proxy help`	显示帮助

6. 原理

flowchart TD
    A["iTerm / zsh"] --> B["geph_proxy on"]
    B --> C{"HTTP 9910<br/>可用？"}
    C -->|是| D["设置 HTTP_PROXY / HTTPS_PROXY"]
    C -->|否| E{"SOCKS5 9909<br/>可用？"}
    E -->|是| F["设置 SOCKS5H 代理"]
    E -->|否| G["尝试启动 Geph<br/>等待端口开放"]
    G --> C
    D --> H["Geph 本地代理"]
    F --> H
    H --> I["Geph 隧道"]
    I --> J["国外网络"]
    B --> K["NO_PROXY 国内域名"]
    K --> L["直连"]

6.1 环境变量代理

macOS 终端程序通常通过环境变量决定是否使用代理：

http_proxy / HTTP_PROXY：HTTP 请求；
https_proxy / HTTPS_PROXY：HTTPS 请求；
all_proxy / ALL_PROXY：部分客户端使用的兜底代理；
no_proxy / NO_PROXY：不经过代理的域名。

脚本优先使用 Geph 的 HTTP 端口，因为多数命令行工具对 HTTP 代理兼容性最好。HTTP 不可用但 SOCKS5 可用时，再使用 socks5h://，让 DNS 也通过代理解析。

6.2 为什么先验证再设置

端口存在不代表节点可达。Geph 可能已经监听 9910，但远端节点暂时超时；此时直接把环境变量写进终端，会让后续 curl、brew、git 一起卡住。

脚本先执行一个 204 测试：

curl --proxy "$proxy_url" --noproxy "" \
  --max-time 6 --output /dev/null \
  --write-out '%{http_code}\n' \
  https://www.gstatic.com/generate_204

只有返回 204、其他 2xx/3xx 状态且 curl 正常退出，脚本才设置代理。全部失败时会执行等价于 unproxy 的清理操作。

6.3 为什么放在后台也能用

Geph 开启本地代理后，终端只需要连接本机回环地址：

127.0.0.1:9910
127.0.0.1:9909

Geph 客户端可以留在菜单栏或后台，不必每执行一条命令就手动切换节点。当前终端保留代理变量，后续子进程会自动继承。

7. 国内域名直连

脚本默认把以下一类域名加入 NO_PROXY：

.cn
.baidu.com
.qq.com
.tencent.com
.aliyun.com
.alibaba.com
.taobao.com
.jd.com
.bilibili.com
.zhihu.com
.gitee.com
.huaweicloud.com
...

完整列表在脚本的 GEPH_NO_PROXY_DOMAINS 数组中。这样可以避免访问常见国内站点时绕一圈国外节点。

需要追加自己的内网或国内域名时，在加载脚本前设置：

export GEPH_EXTRA_NO_PROXY=".example.cn,.corp.internal"
source "$HOME/.local/share/geph-proxy/geph_proxy.zsh"
geph_proxy on

NO_PROXY 是基于域名的客户端约定，不是完整的 GeoIP 分流。不同程序对通配符和结尾匹配的支持并不完全一致；直接访问国内 IP、没有域名后缀的地址，或本身不读取环境变量的程序，仍可能不受 NO_PROXY 控制。

需要浏览器、所有进程和 IP 级分流时，应使用 Geph 客户端的全局路由能力或独立规则代理，而不是只依赖终端环境变量。

8. 端口一致性检查

8.1 Geph 端

在 Geph 设置中查看：

SOCKS5 端口：9909
HTTP 代理端口：9910

8.2 脚本端

脚本顶部对应变量为：

typeset -g GEPH_HTTP_PORT="${GEPH_HTTP_PORT:-9910}"
typeset -g GEPH_SOCKS_PORT="${GEPH_SOCKS_PORT:-9909}"

如果你把 Geph 的 HTTP 端口改成了 10010，就要让脚本看到相同值：

export GEPH_HTTP_PORT=10010
source "$HOME/.local/share/geph-proxy/geph_proxy.zsh"
geph_proxy ports

更长期的做法是直接修改脚本中的默认端口。端口不一致时，原因为连接拒绝，解决方案只有两种：把 Geph 改回默认值，或把脚本改成 Geph 的实际值。

9. 验证清单

9.1 检查端口

geph_proxy ports

期望 9909、9910 至少有一个显示“正在监听”。

9.2 开启但跳过测速

geph_proxy on --quick

期望看到：

✓ Geph HTTP 可用：http://127.0.0.1:9910（…… ms）
✓ 当前终端已接入：Geph HTTP

如果 HTTP 不通但 SOCKS5 正常，则会显示 Geph SOCKS5。

9.3 检查国外访问

curl --noproxy '' -sS -o /dev/null \
  --max-time 15 \
  -w 'HTTP %{http_code}\n' \
  https://www.gstatic.com/generate_204

期望返回 HTTP 204。--noproxy '' 的作用是确认这次测试没有被当前 shell 的 NO_PROXY 意外绕过。

9.4 检查代理变量

geph_proxy status
env | grep -i '_proxy='

9.5 测速

geph_proxy test

免费账号有限速，速度会明显低于本地直连或其他付费线路。这个结果用于判断“是否可用”，不适合当作线路排名。

10. 优缺点

项目	评价
稳定性设计	脚本先验证真实外网再设置代理，避免端口假在线拖住所有终端命令
成本	可以使用 Geph 免费账号，不依赖商业镜像会员
终端覆盖	能覆盖 `curl`、`git`、Homebrew、npm、pip 等继承环境变量的 CLI
后台使用	Geph 留在菜单栏，终端按需连接本机端口，不必频繁切换窗口
国内直连	对常见 `.cn` 和国内大站配置 `NO_PROXY`，减少无效绕行
限速	免费版存在速度限制，大文件下载仍应优先使用国内镜像
覆盖范围	只接管读取代理环境变量的程序，不替代系统级 VPN
分流精度	`NO_PROXY` 不是 GeoIP；国内 IP、特殊客户端和部分原生应用可能不受控
SSH / UDP	普通 SSH、ping、UDP 通常不读取 HTTP 代理变量，需要各自配置

11. 常见问题

现象	原因	处理
`9910/9909` 未监听	Geph 本地代理未真正启动	关闭再开启“本地代理”，完全退出 Geph 后重开
`curl: (7)`	本机端口没有监听，或连接被拒绝	运行 `geph_proxy ports`，核对端口
`Proxy CONNECT aborted` / `curl: (28)`	本地端口通了，但 Geph 节点连接超时	更换 Geph 节点，或重新连接
返回 `HTTP 407`	本地代理要求认证	检查 Geph 设置；本脚本默认适配无认证的本机代理
`geph_proxy: command not found`	zsh 未加载脚本，或 `source` 路径不正确	先运行 `whence -w geph_proxy`，再检查 `~/.zshrc` 中的脚本路径
只有新终端生效	函数只在 source 后加载	运行 `exec zsh` 或重新打开 iTerm
国内站点仍走代理	该域名不在 `NO_PROXY` 中，或程序不读取该变量	用 `GEPH_EXTRA_NO_PROXY` 追加域名
`git@github.com:...` 不走代理	SSH 不读取 `HTTPS_PROXY`	改用 HTTPS remote，或单独配置 SSH `ProxyCommand`
浏览器没有变化	浏览器不继承 iTerm 的环境变量	使用 Geph 的系统代理/全局 VPN，或浏览器独立代理配置

全部失败后的恢复

脚本在失败时会主动清除代理变量。也可手动执行：

geph_proxy off

如果仍有残留，可以新开一个 iTerm 标签页；新的 shell 不会继承旧标签页里的临时代理变量。

12. 安全与使用边界

只从 Geph 官网或 Geph 官方 GitHub 获取客户端和资料。
不要把来源不明的代理二进制、配置或证书加入 PATH。
免费代理不等于匿名保证。是否需要信任第三方网络、是否会暴露登录信息，仍取决于自己的风险模型和服务条款。
代理只改变网络路径，不会自动校验下载文件是否完整；软件包仍应使用官方签名或哈希校验。
不要让 AI 或其他工具在未经确认的情况下修改节点、系统 VPN、证书和网络规则。

13. 本地使用流程总结

从 Geph 官网安装并启动 Geph。
在“设置 → 本地代理”确认 HTTP 9910、SOCKS5 9909。
打开 geph_proxy.zsh 完整源码，阅读后下载到自己的脚本目录。
在 ~/.zshrc 中 source 该文件，路径必须与脚本实际位置一致。
重新打开 iTerm，运行 whence -w geph_proxy 确认函数已加载。
运行 geph_proxy ports 检查 Geph 端口。
运行 geph_proxy on --quick 验证外网。
需要查看速度时运行 geph_proxy test。
不再需要终端代理时运行 geph_proxy off。

完整脚本下载：geph_proxy.zsh

Rocky‘s Blog - Geph

Geph 免费版 + iTerm：给 macOS 终端补一层可用的外网代理

Geph 免费版 + iTerm：给 macOS 终端补一层可用的外网代理

1. 目标与适用边界

2. 实测环境

3. 安装并配置 Geph

3.1 安装客户端

3.2 开启本地代理

3.3 先验证端口

4. 阅读、下载并加载终端脚本

4.1 先阅读源码，再下载

4.2 加入你自己的 ~/.zshrc

4.3 应用后的基础测试

5. 使用方式

5.1 开启、验证并测速

5.2 只验证外网，不下载测速

5.3 查看状态

5.4 重新测速

5.5 检查端口

5.6 关闭代理

5.7 命令速查

6. 原理

6.1 环境变量代理

6.2 为什么先验证再设置

6.3 为什么放在后台也能用

7. 国内域名直连

8. 端口一致性检查

8.1 Geph 端

8.2 脚本端

9. 验证清单

9.1 检查端口

9.2 开启但跳过测速

9.3 检查国外访问

9.4 检查代理变量

9.5 测速

10. 优缺点

推荐的使用组合

11. 常见问题

全部失败后的恢复

12. 安全与使用边界

13. 本地使用流程总结

4.2 加入你自己的 `~/.zshrc`