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

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. 实测环境

端口必须与 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 中进入：

设置 → 局域网 → 本地代理

确认：

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

“自动配置代理”会尝试修改系统代理。本文的脚本只改当前 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

它会依次执行：

1. 测试 Geph HTTP 127.0.0.1:9910；
2. HTTP 不行时测试 SOCKS5 127.0.0.1:9909；
3. 两个端口都未开放时尝试启动 Geph 并等待；
4. 通过候选代理访问国外 HTTPS 测试站；
5. 只有外网访问成功才设置终端代理变量；
6. 默认下载约 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 命令速查

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. 优缺点

推荐的使用组合

GitHub / Homebrew / PyPI
  → 已有国内镜像优先

镜像未覆盖的 HTTPS 域名
  → Geph 终端代理

浏览器和全系统流量
  → 按需使用 Geph 客户端的系统级能力

11. 常见问题

全部失败后的恢复

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

geph_proxy off

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

12. 安全与使用边界

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

13. 本地使用流程总结

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

完整脚本下载：geph_proxy.zsh