macOS 系统代理(System Proxy)默认不接管终端命令行工具。开发者有两条路可选:轻量可控方案是在 ~/.zshrc 中添加 proxy_on / proxy_off 环境变量函数,并为 Git SSH 配置 ProxyCommand nc -X 5 -x 127.0.0.1:7897 %h %p;全自动省心方案则是直接在 Clash Verge Rev 中开启 Service Mode + TUN 模式,从网络层接管所有 CLI 与 IDE 流量。
对 macOS 开发者来说,最令人崩溃的场景莫过于:浏览器里打开 GitHub、Stack Overflow 和官方文档飞快,一回到 iTerm2 或 macOS 自带终端敲下 git pull、brew install、npm install 或打开 Cursor 写代码,终端立刻卡死在 Cloning into... 或抛出 Failed to connect to github.com port 443。
这并不是你的节点挂了,而是 macOS 代理机制的“历史遗留特性”。本文将一次性带你打通 Zsh 终端、Git(HTTPS + SSH)、Homebrew、npm/pnpm/pip/Cargo、以及 Cursor / VS Code 的全栈代理配置,并对比 环境变量方案 与 TUN 模式方案 的优劣。
一、先搞懂原理:为什么系统代理管不到终端?
当你打开 Clash Verge Rev 的 “系统代理(System Proxy)” 时,它只是修改了 macOS 系统设置里对应网卡的 HTTP/HTTPS/SOCKS 代理注册表。
- 浏览器(Safari / Chrome / Arc):启动时会主动向 macOS 查询系统代理设置,因此能自动走 Clash。
- 终端命令行工具(curl / git / ssh / brew / go / pip / cargo):源于 Unix/Linux 生态,它们默认不读取 macOS 系统设置,只认两样东西:
- 当前 Shell 会话中的环境变量(
http_proxy、https_proxy、all_proxy、no_proxy); - 各自专属的配置文件(如
~/.gitconfig、~/.ssh/config、~/.npmrc)。
- 当前 Shell 会话中的环境变量(
第一步:先确认你的 Clash 混合端口(Mixed Port)
在执行任何配置前,打开你的 Clash 客户端 → 设置(Settings),查看 端口设置 / 混合端口(Mixed Port):
- Clash Verge Rev / Clash Party:默认混合端口一般为
7897; - ClashX.Meta:默认混合端口一般为
7890。
下文所有代码均以 Clash Verge Rev 默认端口
7897为例。如果你使用的是7890或自定义端口,请统一替换为你的实际端口号。
二、最优雅的终端方案:在 ~/.zshrc 添加一键开关函数
不要把 export http_proxy=... 死板地写死在 ~/.zshrc 顶层,否则一旦你哪天关闭了 Clash,所有终端命令都会因为连不上本地端口而报错。最推荐的做法是定义两个极简的 Shell 函数:proxy_on 和 proxy_off,随用随开,并配好 no_proxy 防止误伤本地 localhost 开发调试。
1. 编辑 ~/.zshrc
打开终端,使用你顺手的编辑器打开 ~/.zshrc(如 nano ~/.zshrc 或 code ~/.zshrc),在文件末尾追加以下内容:
# Clash Mac 终端代理一键开关(默认端口 7897,ClashX.Meta 请改为 7890)
CLASH_PORT=7897
proxy_on() {
export http_proxy="http://127.0.0.1:${CLASH_PORT}"
export https_proxy="http://127.0.0.1:${CLASH_PORT}"
export all_proxy="socks5h://127.0.0.1:${CLASH_PORT}"
export HTTP_PROXY="$http_proxy"
export HTTPS_PROXY="$https_proxy"
export ALL_PROXY="$all_proxy"
export no_proxy="localhost,127.0.0.1,::1,10.0.0.0/8,172.16.0.0/12,.local"
export NO_PROXY="$no_proxy"
echo "Clash 终端代理已开启 (127.0.0.1:${CLASH_PORT})"
}
proxy_off() {
unset http_proxy https_proxy all_proxy HTTP_PROXY HTTPS_PROXY ALL_PROXY no_proxy NO_PROXY
echo "Clash 终端代理已关闭"
}
proxy_check() {
echo "当前环境变量: http_proxy=${http_proxy:-未设置}"
curl -I -m 5 https://www.google.com 2>/dev/null | head -n 1 || echo "Google 连通测试失败"
}
细节加分项:注意
all_proxy里我们用的是socks5h://而不是socks5://。多出来的那个h表示“让代理服务器解析目标域名(Remote DNS)”,能有效防止本地 DNS 污染导致终端连接失败。
2. 让配置生效并测试
source ~/.zshrc
proxy_on
proxy_check
如果终端输出 HTTP/2 200,说明当前终端会话已经稳定接入 Clash!
三、Git 代理全攻略:同时搞定 HTTPS 与 SSH 协议
很多开发者配了 http_proxy 后发现 git clone https://github.com/... 变快了,但一执行 git clone git@github.com:... 依然卡死。这是因为 git@github.com 走的是 SSH 协议(22 端口),完全不看 http_proxy 环境变量。
1. Git HTTPS 协议代理(按域名精准生效)
建议只针对 github.com 单独配置代理,避免影响公司内网 GitLab 或 Gitee 的推送速度:
git config --global http.https://github.com.proxy http://127.0.0.1:7897
git config --global https.https://github.com.proxy http://127.0.0.1:7897
日后如果想取消,执行:
git config --global --unset http.https://github.com.proxy
git config --global --unset https.https://github.com.proxy
2. Git SSH 协议代理(核心:ProxyCommand)
编辑(或新建)~/.ssh/config 文件,为 GitHub 指定通过 macOS 自带的 nc(netcat)走 Clash 的 SOCKS5 代理。如果你的宽带或公司防火墙封锁了 22 端口,顺手把端口改成 GitHub 官方支持的 443 端口(ssh.github.com),稳如磐石:
Host github.com
HostName ssh.github.com
User git
Port 443
ProxyCommand nc -X 5 -x 127.0.0.1:7897 %h %p
参数说明:
-X 5:指定使用 SOCKS5 代理协议;-x 127.0.0.1:7897:指定 Clash 本地监听地址与混合端口;%h %p:自动代入目标主机名与端口。
保存后在终端验证 SSH 连通性:
ssh -T git@github.com
看到 Hi <your-username>! You've successfully authenticated, but GitHub does not provide shell access. 即大功告成。
四、Homebrew 与主流包管理器代理配置
1. Homebrew
Homebrew 底层依赖 curl 和 git。只要你在当前终端执行过 proxy_on,brew update、brew install、brew upgrade 就会自动继承 http_proxy / https_proxy / all_proxy 环境变量,无需单独改 Homebrew 配置。
如果你偶尔只想让单次命令走代理,也可以前缀临时注入:
ALL_PROXY=socks5h://127.0.0.1:7897 brew install ripgrep
2. Node.js(npm / pnpm / yarn)与 Python(pip / uv)
- npm / pnpm / yarn:现代版本均自动读取终端的
HTTP_PROXY/HTTPS_PROXY环境变量。若你在图形界面或 CI 脚本中需要持久化,可在~/.npmrc中写入(注意不要与国内淘宝镜像混用导致绕路):proxy=http://127.0.0.1:7897 https-proxy=http://127.0.0.1:7897 - pip / uv:同样原生遵循
http_proxy与https_proxy。在执行proxy_on后的终端里直接pip install或uv pip install即可高速拉取 PyPI 与 HuggingFace 依赖。
3. Rust(Cargo)与 Go
- Cargo:执行
proxy_on后即可自动生效;也可在~/.cargo/config.toml中持久化:[http] proxy = "http://127.0.0.1:7897" - Go Modules:Go 语言默认支持
HTTPS_PROXY,同时建议搭配国内或官方GOPROXY(如go env -w GOPROXY=https://proxy.golang.org,direct)在开启proxy_on时拉取海外私有库。
五、Docker Desktop、AI CLI 与多语言开发生态的专项代理技巧
除了上面最常用的 Git、Homebrew 和包管理器,现代 macOS 开发者在日常工作中还会频繁接触容器化构建、大模型命令行助手以及各类版本管理工具。这一节针对高频卡顿场景给出直接落地的配置方案:
1. Docker Desktop 与 OrbStack 拉取海外镜像
当你执行 docker pull 从 Docker Hub、GHCR(ghcr.io)或 Quay 拉取基础镜像时,Docker 守护进程运行在独立的轻量 Linux 虚拟机内部,它既不读取 macOS 系统代理,也不读取你终端里 export 出来的 http_proxy。
- Docker Desktop 配置方法:打开 Docker Desktop → 右上角齿轮 Settings → Resources → Proxies → 开启 Manual proxy configuration,在 Web Server (HTTP) 和 Secure Web Server (HTTPS) 中填入
http://127.0.0.1:7897(新版 Docker Desktop 会自动将其映射给宿主机代理),在 Bypass proxy settings 中填入localhost,127.0.0.1,.local,10.0.0.0/8,点击 Apply & Restart 即可高速拉取海外镜像。 - OrbStack 用户:OrbStack 对 macOS 系统代理和 Clash TUN 模式的原生适配做得非常出色,通常只需打开系统代理或 TUN 模式即可自动生效,无需额外手动填写代理地址。
2. AI 命令行工具(Claude Code / OpenAI Codex / Python HuggingFace)
如今越来越多开发者直接在终端使用 AI 编程代理(如 Claude Code、Aider、OpenAI SDK)或用 Python 拉取 HuggingFace 权重文件:
- Node.js 系 CLI(如 Claude Code):部分新版 Node.js 内置的
undici/fetch客户端默认需要显式开启代理环境变量支持,且对ALL_PROXY=socks5h://...的兼容度不如 HTTP 代理。建议确保终端里已经导出HTTP_PROXY=http://127.0.0.1:7897与HTTPS_PROXY=http://127.0.0.1:7897(注意大小写同时存在,我们前面提供的proxy_on函数已经完美覆盖了这一点)。 - Python 生态(
requests/httpx/huggingface-cli):如果你在执行proxy_on后遇到 Python 报错Missing dependencies for SOCKS support,这是因为all_proxy=socks5h://...触发了 Python 底层检查,而当前虚拟环境没有安装pysocks库。解决方法非常简单:要么在虚拟环境安装pip install pysocks,要么临时执行unset all_proxy ALL_PROXY,只保留http_proxy与https_proxy,Python 就能流畅走 HTTP 代理。
3. 版本管理工具(nvm / fnm / pyenv / rustup / sdkman)
安装不同版本的 Node.js、Python 或 Rust 工具链时,下载源大多托管在 GitHub Releases 或海外 CDN。只要当前终端执行过 proxy_on,nvm install、pyenv install、rustup update 底层调用的 curl 都会自动走代理通道。如果发现 curl 提示 SSL 证书校验异常,请检查你的 Clash 节点是否正常,切勿随意在全局配置中关闭 SSL 证书校验(insecure),以免引入中间人攻击风险。
4. Java / Maven / Gradle 与 Android SDK 代理避坑
从事后端或移动端开发的 Mac 工程师,经常会在构建 Maven、Gradle 项目或更新 Android Studio SDK 时卡在依赖下载。与 Node.js 和 Python 不同,JVM 生态工具通常不会直接读取终端里的 http_proxy 环境变量,而是需要显式传递 JVM 系统参数或在专属配置文件中声明:
- Gradle 全局配置:在
~/.gradle/gradle.properties中添加以下参数(如果日常不常走代理,建议按需取消注释,避免离线构建时报错):systemProp.http.proxyHost=127.0.0.1 systemProp.http.proxyPort=7897 systemProp.https.proxyHost=127.0.0.1 systemProp.https.proxyPort=7897 systemProp.http.nonProxyHosts=localhost|127.0.0.1|*.local - 单次命令行临时代理:不想污染全局配置文件时,直接在构建命令中附加参数即可,例如执行
./gradlew build -Dhttps.proxyHost=127.0.0.1 -Dhttps.proxyPort=7897。
5. 多终端环境(iTerm2 / Warp / Ghostty / tmux)的会话隔离技巧
很多开发者习惯同时打开多个终端标签页,或者使用 tmux 保持长驻开发会话。需要特别留意的是:在终端里执行的 proxy_on 只对当前 Shell 进程及其子进程生效,不会影响已经打开的其他标签页。
如果你希望在终端提示符(Prompt)里一眼看清“当前窗口到底有没有开代理”,防止误把本地调试请求发到代理端口,可以在 ~/.zshrc 的 RPROMPT 或 Powerlevel10k / Starship 主题中增加一个环境变量状态指示;或者更简单地,把“需要走外网拉依赖”的操作固定放在同一个标签页里,拉取完成后随手敲一句 proxy_off 恢复纯净环境。而在使用 sudo 执行高权限命令时,macOS 默认出于安全策略会重置环境变量,如果你需要让 sudo 命令也继承当前终端的代理设置,务必加上 -E 参数(即 sudo -E ...),否则 sudo 内部的下载依然会直连超时。
六、Cursor 与 VS Code 代理配置(避开 AI 补全断连)
作为基于 Electron 的现代 IDE,Cursor 和 VS Code 默认会尝试继承系统代理,但在涉及 HTTP/2 流式响应、AI Tab 自动补全、Claude / GPT 模型对话以及扩展商店下载 时,经常出现偶发断连。
推荐按以下 3 步完成最优配置:
- 检查编辑器代理设置:打开 Cursor / VS Code,按
Command + ,打开设置,搜索proxy:- Http: Proxy(
http.proxy):留空即可自动继承系统代理;如果系统代理不稳定,可显式填入http://127.0.0.1:7897。 - Http: Proxy Support(
http.proxySupport):建议设为override或on,确保内置插件与语言服务器(LSP)也遵循代理。
- Http: Proxy(
- 排查 HTTP/2 兼容性(Cursor 专属技巧):部分网络环境下,Cursor 的 AI 流式对话在代理通道中走 HTTP/2 容易卡死。如果在 Cursor 中频繁遇到
Connection failed或无限转圈,打开设置搜索disableHttp2,勾选Cursor > General: Disable Http2,强制回退到更稳健的 HTTP/1.1。 - 节点地区避坑(最关键):Cursor 底层大量调用 OpenAI 与 Anthropic(Claude)接口,严禁使用香港节点!请在 Clash 中为
cursor.sh、openai.com、anthropic.com分流指定 日本、新加坡或美国节点。如果你需要长期高并发稳定调用 AI 开发工具的专线线路,可以参考 唯兔云 Mac 端实测与套餐方案。
七、开发者专属排错清单:4 条命令秒查代理异常
当终端命令依然卡死或报错时,不要盲目重启电脑,按顺序敲下面 4 条诊断命令,30 秒内就能锁定病灶:
# 1. 确认 Clash 本地混合端口是否处于 LISTEN 状态
lsof -nP -iTCP:7897 -sTCP:LISTEN
# 2. 检查当前终端会话的代理环境变量是否已正确导出(注意是否误带了多余引号或旧端口)
env | grep -i proxy
# 3. 绕过环境变量,直接指定端口测试代理通道本身是否连通
curl -v --max-time 8 -x http://127.0.0.1:7897 https://api.github.com/zen
# 4. 检查 Git 全局与当前项目仓库是否残留了冲突的旧代理配置
git config --list --show-origin | grep -i proxy
实战经验提醒:第四条命令救过无数开发者的命!很多人以前在某个项目目录或 ~/.gitconfig 里随手写死过 http.proxy = http://127.0.0.1:7890,后来换了 Clash Verge Rev(默认 7897),结果无论怎么改终端环境变量,git pull 依然报错 Failed to connect to 127.0.0.1 port 7890。用 git config --list --show-origin 一眼就能揪出残留的旧配置所在文件路径。
八、终极省心替代方案:用 TUN 模式接管一切
看到这里,如果你觉得给每个开发工具单独配环境变量、改 .ssh/config、配 IDE 设置还是太繁琐——尤其是当你还要使用 Docker Desktop、Kubernetes(kubectl)、Postman、Warp 终端、或者各种不支持系统代理的桌面端 App 时,Clash 提供了一个“一劳永逸”的方案:开启 TUN 模式(增强模式)。
环境变量方案 vs TUN 模式对比
| 维度 | 终端环境变量方案(proxy_on) | Clash TUN 模式(虚拟网卡接管) |
|---|---|---|
| 接管范围 | 仅限当前终端及显式配置的 CLI 工具 | 整台 Mac 所有进程(终端、Git、Docker、游戏、桌面 App) |
| 配置复杂度 | 需维护 ~/.zshrc 与 ~/.ssh/config | 客户端内安装 Service Mode 后一键开关 |
| 对本地开发与内网的影响 | 极低(可控度最高,通过 no_proxy 精准排除) | 需注意在 fake-ip-filter 中放行公司内网域名 |
| 系统权限要求 | 无需 root 权限 | 需要授权安装 macOS 辅助服务(Service Mode) |
| 推荐人群 | 追求极致可控、频繁连接复杂企业内网的开发者 | 希望全机所有工具开箱即用、不想折腾配置的开发者 |
最佳实践建议:
- 日常在家办公或个人开发,直接开启 Clash Verge Rev 的 Service Mode + TUN 模式,99% 的命令行与 IDE 工具零配置直接起飞;
- 在需要连接公司复杂内网 VPN 或调试本地多网卡容器时,关闭 TUN 模式,切回 系统代理 +
proxy_on按需开启,两者无缝互补。
想深入了解 TUN 模式背后的三层虚拟网卡原理、Fake-IP 避坑与 DNS 防污染调优?欢迎继续阅读本系列 L3 极客篇:Clash Mac TUN 模式与增强模式原理及深度调优。如果你在配置过程中遇到了其他报错,也可以对照 Clash Mac 15 个高频易错点清单 快速定位。
常见问题解答(FAQ)
为什么 Chrome 访问 GitHub 秒开,但终端里执行 git clone 和 brew install 却一直超时? +
因为 macOS 的“系统代理(System Proxy)”只是一个供图形界面应用自愿读取的系统配置项,Safari、Chrome 会遵循它,但 curl、git、brew、ssh、pip、cargo 等命令行工具默认直接忽略系统代理,尝试直连目标服务器。你需要通过终端环境变量或开启 Clash 的 TUN 模式来引导它们的流量。
Clash Verge Rev、ClashX.Meta 和 Clash Party 的本地代理端口是一样的吗? +
不完全一样,配置前务必先在客户端“设置”里确认端口号!Clash Verge Rev 和 Clash Party 默认混合端口(Mixed Port,同时支持 HTTP 与 SOCKS5)通常为 7897;ClashX.Meta 默认混合端口通常为 7890。下文命令中如果使用 ClashX.Meta,请将 7897 替换为 7890。
配置了 http_proxy 后,为什么连本地 localhost:3000 调试接口或公司内网 GitLab 反而报错了? +
因为没有配置 no_proxy(排除列表),导致访问 127.0.0.1、localhost 或内网网段的请求也被发给了 Clash。在导出代理环境变量时,务必同时加上 export no_proxy="localhost,127.0.0.1,::1,10.0.0.0/8,172.16.0.0/12,.local"。
我开了 TUN 模式,还需要再手动配置 ~/.zshrc 的 http_proxy 吗? +
绝大多数情况下不需要。TUN 模式在操作系统底层创建虚拟网卡接管全机三层流量,curl、git、brew、Docker Desktop、Cursor 都能无感走代理。但注意:部分软件(如某些版本的 Git over SSH 或特定 Java/Python 库)在 Fake-IP 下若遇到兼容性问题,配合显式环境变量依然是最稳的备选。
为什么 Cursor 或 VS Code 里的 AI 补全 / Copilot 偶尔提示 Connection Failed 或地区受限? +
常见原因有两个:一是编辑器本身没有继承代理设置,需在 Settings 中检查 http.proxy 并根据需要开启 http.proxySupport;二是你当前 Clash 选中的是香港节点,而 OpenAI、Anthropic(Claude)以及部分 Cursor 模型接口屏蔽了香港 IP,将节点切到日本、新加坡或美国即可解决。
还没有稳定可用的 Clash 订阅?首选 唯兔云
¥14.9/月起,100 GB / 月,提供年付低至 ¥6.66/月、月付 100GB–1.4TB 及永久不限时包,优惠码 rabbit,原生兼容 ClashX.Meta / Clash Verge Rev。