Mac 终端代理怎么设置？3 步完成配置、验证与关闭
简答：浏览器能联网、但 Mac 终端里的 curl、Git、brew 或 npm 超时，先确认代理客户端显示的是 HTTP 端口还是 SOCKS5 端口，再执行对应的 export 命令。最快的处理顺序是：设置变量、用 env 和 curl -v 验证、确认无误后再保存到 shell 配置文件；关闭客户端后出现 Connection refused 时，先执行 proxy_off 或 unset 清理残留变量。
定义：Mac 终端代理，是通过 shell 环境变量、系统代理或单个工具配置，让命令行程序经指定的 HTTP、HTTPS 或 SOCKS5 代理访问网络。
先试这一步：30 秒速查终端代理是否生效
浏览器能联网但终端超时，多数情况不是网页本身的问题，而是终端没有拿到代理变量，或把 HTTP 端口和 SOCKS5 端口混用了。本文是第三方使用指南，本文核对日期：2026-11-14。
执行前先替换占位符：把 HTTP端口 和 SOCKS端口 替换成代理客户端实际显示的端口，不要把占位符原样写入配置文件。
| 目的 | 命令 | 判定标准 |
|---|---|---|
| 使用 HTTP/HTTPS 代理 | export http_proxy=http://127.0.0.1:HTTP端口; export https_proxy=http://127.0.0.1:HTTP端口 | 命令无报错，当前 shell 临时保存变量 |
| 使用 SOCKS5 代理 | export all_proxy=socks5h://127.0.0.1:SOCKS端口 | 支持 SOCKS 的程序可尝试通过代理连接 |
| 检查变量 | env | grep -iE '(^|_)(http|https|all|no)_proxy=' | 能看到已设置的变量 |
| 验证 curl | curl -v --max-time 15 https://example.com -o /dev/null | 详细输出出现代理连接、CONNECT 或 SOCKS 协商信息 |
| 临时关闭 | unset http_proxy https_proxy all_proxy no_proxy HTTP_PROXY HTTPS_PROXY ALL_PROXY NO_PROXY | 再次执行 env 检查时没有代理变量 |
curl 手册说明，socks5://由本机解析目标域名，socks5h://要求代理端解析目标域名；HTTP、HTTPS、SOCKS5 的协议前缀必须与实际代理类型匹配。若出现 Connection refused，优先检查端口是否监听；出现 Could not resolve host，优先检查 DNS 或 SOCKS 远程解析。
第 1 步：区分系统代理、终端变量和代理客户端模式
macOS 的系统代理入口是“系统设置 → 网络 → 当前网络服务 → 详细信息 → 代理”。Apple 的说明列出了 HTTP、HTTPS、SOCKS、自动代理发现、PAC 和绕过域名等选项，具体可查看 Apple 的 Mac 代理设置说明。
系统代理和终端代理不是同一层：浏览器或部分图形应用可能读取系统代理或 PAC，但某个终端程序是否读取它，取决于该程序自身实现。相反，export http_proxy=... 只影响当前 shell 及其子进程，不会自动修改 macOS 的系统代理。
先查看网络服务名称：
networksetup -listallnetworkservices
不要默认假定服务一定叫 Wi-Fi，命令输出中的名称才是准确信息。假设输出中存在 Wi-Fi，可查看三类系统代理：
networksetup -getwebproxy "Wi-Fi"; networksetup -getsecurewebproxy "Wi-Fi"; networksetup -getsocksfirewallproxy "Wi-Fi"
如果输出含 Enabled: Yes，表示该网络服务对应的系统代理已启用；如果出现 ** Error: The parameters were not valid.，通常是服务名称写错，应复制 networksetup -listallnetworkservices 的完整名称。
设置前先记录原状态。需要管理员权限时使用以下命令，并把端口替换为实际值：
sudo networksetup -setwebproxy "Wi-Fi" 127.0.0.1 HTTP端口; sudo networksetup -setsecurewebproxy "Wi-Fi" 127.0.0.1 HTTP端口; sudo networksetup -setsocksfirewallproxy "Wi-Fi" 127.0.0.1 SOCKS端口
关闭系统代理：
sudo networksetup -setwebproxystate "Wi-Fi" off; sudo networksetup -setsecurewebproxystate "Wi-Fi" off; sudo networksetup -setsocksfirewallproxystate "Wi-Fi" off
如果同时使用 Wi-Fi 和以太网，需要分别查看和恢复；只关闭 Wi-Fi 不代表以太网的代理设置也已关闭。若启用了 TUN 模式，又手动设置了系统代理和终端变量，可能出现重复接管或请求路径难以判断。排查时先临时关闭其中一层，只保留一种方式，再用 curl -v 重测。
第 2 步：按 zsh 或 bash 保存代理开关，并保留回滚方法
先确认当前 shell：
echo "$SHELL"; ps -p $$ -o command=
macOS 新终端通常使用 zsh，但不要只凭系统版本判断。当前 shell 是 zsh 时，常见配置文件是 ~/.zshrc；bash 可能读取 ~/.bash_profile 或 ~/.bashrc，实际以本机启动方式为准。Terminal.app 和 iTerm2 都会启动 shell，通常读取同一套 shell 配置文件；如果两者表现不同，应分别执行上面的命令确认启动的 shell 和加载文件。
以下示例以 zsh 为例。先备份，再执行；执行前必须把 HTTP端口 和 SOCKS端口替换为真实数字：
cp ~/.zshrc ~/.zshrc.backup-2026-11-14
cat >> ~/.zshrc <<'EOF'
proxy_on() {
export http_proxy="http://127.0.0.1:HTTP端口"
export https_proxy="http://127.0.0.1:HTTP端口"
export all_proxy="socks5h://127.0.0.1:SOCKS端口"
export no_proxy="localhost,127.0.0.1,::1,.local"
export HTTP_PROXY="$http_proxy"
export HTTPS_PROXY="$https_proxy"
export ALL_PROXY="$all_proxy"
export NO_PROXY="$no_proxy"
}
proxy_off() {
unset http_proxy https_proxy all_proxy no_proxy HTTP_PROXY HTTPS_PROXY ALL_PROXY NO_PROXY
}
EOF
source ~/.zshrc
上面的 heredoc 会原样写入内容，因此必须在执行前替换端口。之后运行 proxy_on 才会启用代理；这属于“永久保存开关”，不是新开终端后自动启用。关闭客户端后若运行命令出现 Connection refused，执行 proxy_off。
追加前先检查是否已有同名函数：
grep -nE '^[[:space:]]*proxy_(on|off)[[:space:]]*\(\)' ~/.zshrc
如已有同名函数，应编辑并替换旧段，不要重复追加。回滚方式是：
mv ~/.zshrc.backup-2026-11-14 ~/.zshrc; exec zsh
如果当前使用 bash，应将备份和追加目标改成实际加载的 ~/.bash_profile 或 ~/.bashrc，不要把 zsh 配置直接写入 bash 文件。
代理用户名和密码不要直接写入命令、函数或 shell 历史。密码中含 @、:、# 等字符时还涉及 URL 编码；更稳妥的做法是使用工具的凭据存储或交互式认证。
第 3 步：工具单独配置与撤销方法
| 工具 | 优先检查 | 单独配置 | 撤销或恢复 |
|---|---|---|---|
| Git HTTPS | git config --global --get http.proxy | git config --global http.proxy http://127.0.0.1:HTTP端口 | git config --global --unset http.proxy |
| Git 按域名 | 确认远程 URL 与域名 | git config --global http.https://github.com.proxy http://127.0.0.1:HTTP端口 | git config --global --unset http.https://github.com.proxy |
| Homebrew | env | grep -i proxy | 使用 http_proxy、https_proxy 或 all_proxy | proxy_off 或执行 unset |
| npm | npm config get proxy; npm config get https-proxy | npm config set proxy http://127.0.0.1:HTTP端口; npm config set https-proxy http://127.0.0.1:HTTP端口 | npm config delete proxy; npm config delete https-proxy |
| pip | python3 -m pip config list | python3 -m pip install --proxy http://127.0.0.1:HTTP端口 包名 | 删除 pip 配置中的 proxy，或改用未设置代理的 shell |
| Docker Desktop | Settings → Resources → Proxies | 在 Docker Desktop 的 Proxies 页面选择系统代理或手动填写 | 关闭 Manual proxy configuration 或恢复系统代理 |
| Git SSH | ssh -G [email protected] | grep -i proxycommand | 在 ~/.ssh/config 添加 ProxyCommand | 删除新增的 Host 段 |
Git 的关键点是不要设置不存在的 https.proxy 键。Git 官方 git-config 文档定义的是 http.proxy，它用于需要 curl 的 HTTP、HTTPS 和 FTP 远程；按 URL 区分时可使用 http.<url>.proxy。因此 Git HTTPS 的正确设置和撤销分别是：
git config --global http.proxy http://127.0.0.1:HTTP端口; git config --global --unset http.proxy
Git SSH 不读取 http.proxy。先备份配置：
cp ~/.ssh/config ~/.ssh/config.backup-2026-11-14 2>/dev/null || touch ~/.ssh/config
编辑 ~/.ssh/config，加入以下段，并将 SOCKS端口 替换为真实端口：
Host github.com
HostName github.com
ProxyCommand /usr/bin/nc -X 5 -x 127.0.0.1:SOCKS端口 %h %p
nc 手册说明，-X 5指定 SOCKS5，-x指定代理地址；macOS 自带 nc 的参数应先用 nc -h核对。验证：
ssh -T [email protected]
如果出现 Could not resolve hostname、Connection refused 或 nc: invalid option，分别检查目标解析、SOCKS 端口和本机 nc 参数。回滚时只删除新增的 Host github.com 段，或恢复备份：
mv ~/.ssh/config.backup-2026-11-14 ~/.ssh/config
Homebrew 官方文档说明，它会使用 http_proxy、https_proxy、all_proxy 和 no_proxy影响下载所用的 curl、Git 和 svn。验证可执行：
brew update -v
npm 可使用环境变量，也可单独配置 proxy 和 https-proxy；相关字段与撤销方式见 npm 配置文档。pip 支持 --proxy scheme://[user:passwd@]proxy.server:port、配置文件和标准环境变量，但使用 SOCKS 地址前应确认当前 pip 与依赖支持，不要把 HTTP 代理端口误写成 SOCKS 端口；参见 pip 用户指南。
Docker Desktop 不等于终端环境变量。进入 Settings → Resources → Proxies，按当前界面选择系统代理或手动输入 HTTP、HTTPS、SOCKS5 代理地址；Docker 文档明确列出了这些代理类型，具体入口和当前版本表现以 Docker Desktop 设置文档为准。不要仅凭终端里的 env输出判断容器流量已经使用代理。
终端仍不走代理：最短排查与完整恢复
- 确认变量是否存在：
env | grep -i proxy。没有输出就执行proxy_on，或重新运行 export。 - 确认本地端口监听：
lsof -nP -iTCP:HTTP端口 -sTCP:LISTEN; lsof -nP -iTCP:SOCKS端口 -sTCP:LISTEN。无输出通常表示端口填错、客户端未启动，或监听地址不是本机。 - 对比本机解析和代理端解析：
curl -v --proxy socks5://127.0.0.1:SOCKS端口 https://example.com -o /dev/null与curl -v --proxy socks5h://127.0.0.1:SOCKS端口 https://example.com -o /dev/null。前者由本机解析域名，后者让代理端解析；两条命令必须使用同一个真实 SOCKS5 端口。 - 检查绕过列表：
echo "$no_proxy"; echo "$NO_PROXY"。目标域名命中排除项时，curl、Git 或其他程序可能直连。 - 检查系统代理状态：
scutil --proxy。这只能说明系统代理状态，不能证明当前 shell 或某个工具已经采用该代理。 - 检查 TUN 或重复接管：如果客户端启用了 TUN，同时又设置了系统代理和 shell 变量，先只保留一种接管方式，再重复 curl 验证；不要用“浏览器能打开”替代终端验证。
- 完整关闭：
unset http_proxy https_proxy all_proxy no_proxy HTTP_PROXY HTTPS_PROXY ALL_PROXY NO_PROXY，再执行git config --global --unset http.proxy、npm config delete proxy和npm config delete https-proxy（仅在此前设置过时执行），最后重新打开终端。
常见报错可这样理解：Connection refused通常表示目标端口没有服务监听；Could not resolve host多与本机解析或 SOCKS 远程解析有关；407 Proxy Authentication Required表示代理要求认证；502 Bad Gateway可能来自代理上游或目标连接，不能单凭这一行判断本机变量错误。应结合 curl -v、lsof和工具自身配置共同判断。
继续排查客户端监听与系统代理
如果终端变量、系统代理和单个工具配置都已清理，但客户端仍然无法连接，可以继续检查客户端实际监听端口、系统代理是否重复启用，以及 DNS 请求是否走了预期路径：
- Clash Verge Rev Mac 使用与代理验收：先确认客户端运行状态和本地监听。
- Mihomo 连接成功但无法上网排查：继续区分节点、DNS 与 TUN 层问题。
- 连接问题排查指南：适合处理多设备或多层代理叠加。
- VPN 配置问题分层排查：适合继续检查连接成功但应用无法访问的情况。
常见问题
Mac 终端设置了代理，为什么浏览器能用但 curl 不能用？
浏览器可能读取 macOS 系统代理或 PAC，而 curl 通常需要环境变量、命令参数或自身配置。先执行 env | grep -i proxy，再用 curl -v 查看是否真的连接了本地代理地址。
HTTP 代理端口和 SOCKS5 端口可以混用吗？
通常不能。HTTP 代理应使用 http:// 前缀，SOCKS5 应使用 socks5:// 或 socks5h://；协议和端口不匹配时，常见结果是 Connection refused、协议错误或 TLS 握手失败。
socks5:// 和 socks5h:// 应该选哪个？
socks5://由本机解析目标域名，socks5h://让代理端解析目标域名。如果本机 DNS 不通但代理端支持远程解析，可优先测试 socks5h://，再用 curl -v 对比结果。
Git 为什么不能用 https.proxy 配置？
Git 官方配置中应使用 http.proxy，它可作用于需要 curl 的 HTTP 和 HTTPS 远程；按域名区分时使用 http.<url>.proxy。https.proxy 不应作为本文配置项使用。
关闭代理客户端后一直出现 Connection refused 怎么办？
先执行 proxy_off，随后运行 env | grep -i proxy；仍有输出时再执行 unset 清理大小写变量。如果 Git、npm 或 networksetup 还有单独配置，还需要分别执行 unset、delete 或关闭命令。
Git SSH 如何通过 SOCKS5 代理？
在 ~/.ssh/config 的目标 Host 段加入 ProxyCommand /usr/bin/nc -X 5 -x 127.0.0.1:SOCKS端口 %h %p，并先用 nc -h 核对本机参数。修改前备份文件，回滚时只删除新增 Host 段或恢复备份。
代理用户名密码能不能直接写进 ~/.zshrc？
不建议。明文凭据可能进入配置备份、命令历史或进程信息；密码还可能因特殊字符造成 URL 解析错误。优先使用工具提供的凭据存储或交互式认证。
相关阅读
参考资料
- Enter proxy server settings on Mac - Apple Support
- curl - How To Use（curl.se）
- Git - git-config Documentation（git-scm.com）
- nc(1) - OpenBSD manual pages（man.openbsd.org）
- Homebrew Documentation: brew(1) - The Package Manager for Everywhere（docs.brew.sh）
- Config - npm Docs
- User Guide - pip documentation（pip.pypa.io）
- Change your Docker Desktop settings