终端代理设置:先说结论
浏览器能上外网,终端里的 git、npm、curl 却连不上,原因是命令行工具大多不读取系统代理设置。解决办法有两个:
方法一:给终端设置代理环境变量。 macOS 和 Linux 上在终端里执行:
export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export all_proxy=socks5://127.0.0.1:7890
方法二:开 TUN 模式。 在代理客户端里打开 TUN 开关,所有程序的流量都会被接管,终端不需要任何设置。
前提是电脑上已经有一个正在运行的代理客户端和可用的机场订阅。还没有的话,先看机场推荐榜和机场客户端大全。
本站主推星岛梦,¥8/月(年付) 起,企业级内网专线。去官网 ↗看完整机场推荐榜 →
第 1 步:确认本地代理端口
代理客户端运行时会在本机监听一个端口,地址是 127.0.0.1,终端代理就是让命令行工具把请求发到这个端口。先找到它:
- Clash Verge Rev:在「设置」页找「端口设置」或「混合端口」。客户端的基本用法见Clash Verge 教程。
- v2rayN:在「设置」的参数设置页面看本地监听端口,主界面底部状态栏通常也有显示。见v2rayN 教程。
- 其他客户端:在设置里找「端口」「Mixed Port」「HTTP 端口」「SOCKS 端口」之类的字样。
常见的默认值有 7890、7897、10808 等,各客户端和各版本不同,也可能被你自己或机场的配置改过,所以以客户端界面上显示的为准。
还要看清端口的类型:
- 混合端口(mixed):同一个端口同时接受 HTTP 和 SOCKS5 两种代理请求。Clash 系客户端一般是这种,下面的命令可以全部填同一个端口。
- 分开的 HTTP 端口和 SOCKS 端口:部分客户端或旧版本是两个不同的数字。这时
http://开头的地址填 HTTP 端口,socks5://开头的地址填 SOCKS 端口。
完成后你应该看到:你手里有一个确定的端口号,并且知道它是混合端口还是分开的两个端口。下文所有示例里的 7890 都替换成它。
第 2 步:设置代理环境变量
这一步按系统分成两种写法:macOS 和 Linux 看本节,Windows 看下一节。
先确认自己用的是哪种 shell
macOS 从 10.15 起默认的 shell 是 zsh,配置文件是 ~/.zshrc;多数 Linux 发行版默认是 bash,配置文件是 ~/.bashrc。不确定的话,在终端执行 echo $SHELL 查看。下面的 export 写法对 zsh 和 bash 都适用;用 fish 的话语法不同,见本节末尾。
三个变量分别管什么
多数命令行工具会读取三个环境变量:http_proxy 用于 HTTP 请求,https_proxy 用于 HTTPS 请求,all_proxy 用于其他协议。
临时生效
在终端里执行开头那三行 export 命令即可。它只对当前这个终端窗口有效,关掉窗口就失效,新开的窗口也不受影响。
取消代理:
unset http_proxy https_proxy all_proxy
只想让某一条命令走代理,可以把变量写在命令前面,不影响后续的命令:
https_proxy=http://127.0.0.1:7890 curl -I https://www.google.com
写成开关命令
不建议把 export 直接写进配置文件让代理永久开启。那样一旦代理客户端没有运行,所有命令行工具都会连接失败。更好的做法是定义两个开关命令,需要时手动开。
把下面的内容加到 ~/.zshrc 的末尾,使用 bash 的话是 ~/.bashrc:
proxy_on() {
export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export all_proxy=socks5://127.0.0.1:7890
export no_proxy=localhost,127.0.0.1,::1
echo "proxy on"
}
proxy_off() {
unset http_proxy https_proxy all_proxy no_proxy
echo "proxy off"
}
保存后执行 source ~/.zshrc 让它生效。以后在终端里输入 proxy_on 开启,输入 proxy_off 关闭。
完成后你应该看到:执行 proxy_on 后终端打印 proxy on,再执行 echo $https_proxy 显示你设置的地址。
几点说明:
no_proxy列出不走代理的地址。本机地址务必写进去,否则访问本地开发服务也会被送到代理。公司内网的域名也可以加在这里,用逗号分隔。- 少数工具只认大写的变量名,如果某个程序不生效,再加一组
HTTP_PROXY、HTTPS_PROXY、ALL_PROXY。 sudo默认不会继承这些变量。需要用sudo -E执行命令,才能把当前的代理设置带过去。socks5://表示域名在本机解析,socks5h://表示域名交给代理端解析。遇到域名解析被污染导致的连接失败,把all_proxy改成socks5h://开头。
fish shell 的写法
fish 不使用 export,设置和取消分别是:
set -gx http_proxy http://127.0.0.1:7890
set -gx https_proxy http://127.0.0.1:7890
set -e http_proxy
set -e https_proxy
大写还是小写变量名
不同工具读取的变量名大小写不完全一样,这是「明明设置了却不生效」的常见原因:
| 变量 | 小写 | 大写 | 说明 |
|---|---|---|---|
| http_proxy | 绝大多数工具读取 | curl 不读取大写形式 | 出于安全原因,curl 只认小写的 http_proxy |
| https_proxy | 读取 | 多数工具也读取 | 两种都设最稳 |
| all_proxy | 读取 | 多数工具也读取 | 部分工具不支持 |
| no_proxy | 读取 | 多数工具也读取 | 写法细节各工具略有差异,例如是否支持网段 |
稳妥的做法是小写为主,某个工具不生效时再补一组大写的。Windows 上环境变量名不区分大小写,不存在这个问题。
Windows:PowerShell 与 CMD 写法
Windows 上两种终端的语法不同,注意区分自己用的是哪一种。
PowerShell:
$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:ALL_PROXY="socks5://127.0.0.1:7890"
PowerShell 取消代理:
Remove-Item Env:HTTP_PROXY, Env:HTTPS_PROXY, Env:ALL_PROXY
CMD(命令提示符):
set http_proxy=http://127.0.0.1:7890
set https_proxy=http://127.0.0.1:7890
set all_proxy=socks5://127.0.0.1:7890
CMD 取消代理,等号后面留空即可:
set http_proxy=
set https_proxy=
set all_proxy=
这些写法同样只对当前窗口有效。CMD 里等号两边不要加空格,地址也不要加引号。
如果你用的是 Git Bash,它的语法和 macOS、Linux 相同,用 export。
Windows 上做成开关命令
PowerShell 也可以像 macOS 那样定义开关函数。先执行 notepad $PROFILE 打开 PowerShell 的配置文件(文件不存在时会提示新建),把下面的内容加进去:
function proxy_on {
$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:NO_PROXY="localhost,127.0.0.1"
"proxy on"
}
function proxy_off {
Remove-Item Env:HTTP_PROXY, Env:HTTPS_PROXY, Env:NO_PROXY -ErrorAction SilentlyContinue
"proxy off"
}
保存后重新打开 PowerShell,输入 proxy_on 或 proxy_off 即可切换。如果提示配置文件因为执行策略无法加载,说明系统禁止运行脚本,需要先了解并调整 PowerShell 的执行策略,或者改用下面的系统环境变量。
想让所有程序长期生效,可以在「系统属性」的「环境变量」里新建用户变量 HTTPS_PROXY 和 HTTP_PROXY。这样设置之后,新打开的终端和程序都会读到它,已经打开的窗口需要重开。和 macOS 一样,长期生效意味着客户端不运行时这些程序会连不上,用完记得删掉。
WSL 的情况稍微复杂。WSL2 默认有自己独立的网络,里面的 127.0.0.1 指向的是 Linux 子系统自身,而不是 Windows。需要在 Windows 的代理客户端里打开「允许局域网连接」,再把代理地址写成 Windows 主机的 IP,或者把 WSL 的网络改为镜像模式。更省事的办法是直接在 Windows 上开 TUN 模式。
第 3 步:给 git 单独设置代理(可选)
环境变量已经能让大多数工具走代理。下面这些单独的设置适合两种情况:希望不依赖终端状态长期生效,或者某个工具不读环境变量。
git
git 通过 HTTPS 访问仓库时会读取环境变量,也可以单独配置,后者不依赖终端状态,更稳定:
git config --global http.proxy http://127.0.0.1:7890
这一条同时管 http:// 和 https:// 开头的仓库地址,不需要再设其他项。
完成后你应该看到:执行 git config --global --get http.proxy 输出你设置的地址,git clone 一个 GitHub 上的 HTTPS 仓库能正常开始下载。
上面是对所有仓库生效。如果只想让 GitHub 走代理,公司内网或国内的代码托管平台保持直连,按域名设置:
git config --global http.https://github.com.proxy http://127.0.0.1:7890
查看和取消:
git config --global --get http.proxy
git config --global --unset http.proxy
注意这些设置只对 HTTPS 方式的仓库地址有效。用 SSH 方式克隆的仓库,地址是 git@github.com: 开头,走的是 SSH 协议,不受 http.proxy 影响。SSH 需要在 ~/.ssh/config 里单独配置,macOS 和多数 Linux 发行版可以这样写:
Host github.com
User git
ProxyCommand nc -X 5 -x 127.0.0.1:7890 %h %p
这里的 nc 需要是支持 -X 参数的版本,Windows 的 Git Bash 里通常改用自带的 connect 工具。嫌麻烦的话,把仓库地址换成 HTTPS 方式,或者开 TUN 模式。
npm 和 pip
npm:
npm config set proxy http://127.0.0.1:7890
npm config set https-proxy http://127.0.0.1:7890
取消:
npm config delete proxy
npm config delete https-proxy
pnpm 和 yarn 也会读取环境变量,一般设置好 http_proxy 和 https_proxy 就行。
pip 可以在单条命令里临时指定,把「包名」换成要安装的包:
pip install --proxy http://127.0.0.1:7890 包名
也可以写入配置长期生效:
pip config set global.proxy http://127.0.0.1:7890
pip config unset global.proxy
第二行是取消命令。
另外提一句:如果目的只是让 npm、pip 下载依赖快一点,换用国内的镜像源往往比走代理更快,也不消耗机场流量。只有在需要访问镜像源里没有的资源时才需要代理。
第 4 步:验证是否生效
设置完成后,用 curl 请求一个只有通过代理才能访问的网站:
curl -I https://www.google.com
-I 表示只取响应头。几秒内返回以 HTTP/2 200 或 HTTP/1.1 200 开头的若干行,说明命令行已经走了代理。返回的状态码是 301、302 之类的跳转也算成功,说明请求已经到达了网站。
Windows 10 及以后的系统自带 curl.exe。PowerShell 里 curl 可能是另一个命令的别名,行为不一样,应输入 curl.exe:
curl.exe -I https://www.google.com
想看请求到底有没有经过代理,加上 -v 参数。输出的前几行里出现连接到 127.0.0.1 和你设置的端口的字样,就是经过了代理。
想一次性看清各个工具当前的代理状态,可以对照下表逐项检查:
| 想确认什么 | 命令 | 正常的结果 |
|---|---|---|
| 环境变量有没有值 | echo $https_proxy(PowerShell 用 $env:HTTPS_PROXY) | 显示你设置的地址 |
| git 有没有单独配置 | git config --global --get http.proxy | 有值说明 git 用的是这个地址 |
| npm 有没有单独配置 | npm config get proxy | 显示地址,或 null 表示没设置 |
| pip 有没有单独配置 | pip config list | 列出 global.proxy 等配置项 |
| 网络是否走通 | curl -I https://www.google.com | 返回 200 开头的响应头 |
| 是否经过本机代理 | curl -v 加上述地址 | 输出里出现 127.0.0.1 和端口 |
工具各自的配置优先级高于环境变量。比如 git 里配置过一个旧端口,即使环境变量是对的,git 仍然会用旧端口,这时就会出现「curl 正常、git 不行」的情况。
常见的失败现象和原因:
- 提示连接被拒绝(Connection refused)。 端口写错了,或者代理客户端没有运行。回到第 1 步核对端口。
- 长时间没有响应后超时。 变量没有生效,或者当前节点不通。执行
echo $https_proxy确认变量有值,再到客户端里换一个节点。 - 用 ping 测试不通。 ping 使用的是 ICMP 协议,不经过 HTTP 和 SOCKS 代理。ping 不通不能说明代理没生效,不要用它来验证。
- 浏览器正常,终端不行。 说明节点没有问题,只是终端没有设置好,重新检查变量名和端口。
其它常用工具的代理设置
除了 git、npm、pip,开发中还会碰到下面这些工具。它们对环境变量的支持程度不同,有的读、有的不读,有的名字里带「proxy」却根本不是网络代理。
| 工具 | 是否读取环境变量 | 说明 |
|---|---|---|
| Homebrew | 是 | 设置好 https_proxy、all_proxy 即可,安装和更新都会走代理 |
| Go 下载依赖 | 是 | go get 读取 https_proxy;注意 GOPROXY 是模块镜像地址,不是网络代理 |
| Rust 的 cargo | 是 | 也可以在 cargo 的配置文件里写 http.proxy |
| conda | 部分 | 可以在 .condarc 里写 proxy_servers,或者改用国内镜像 |
| apt(Ubuntu、Debian) | sudo 下默认不继承 | 用 sudo -E,或在 apt 配置里写 Acquire::http::Proxy |
| Java、Maven、Gradle | 否 | JVM 不读环境变量,需要用 https.proxyHost、https.proxyPort 等系统属性,或在各自配置文件里设置 |
| IDE 内置终端 | 是 | 内置终端会启动一个 shell,读取你的 shell 配置;但 IDE 本身和插件不一定走代理 |
其中最容易混淆的是 Go 的 GOPROXY 和 npm 的 registry。它们指定的是「从哪个镜像服务器下载包」,改成国内镜像后下载可以不经过代理;而 https_proxy 指定的是「网络请求经过哪个代理」。两件事可以同时设置,互不冲突,但不要把机场的本地端口填进 GOPROXY。
按报错原文排查
下面是终端里最常见的几种代理相关报错。报错文字会因工具版本略有不同,关键词对上就行。
Failed to connect to 127.0.0.1 port 7890: Connection refused
请求确实发往了代理,但这个端口上没有程序在监听。要么代理客户端没运行,要么端口填错了。打开客户端核对端口号,注意混合端口和 HTTP 端口的区别。
Failed to connect to github.com port 443 或 Connection timed out
请求没有经过代理,直接去连 GitHub,然后超时。用 echo $https_proxy 看变量是否有值;git 单独设置过 http.proxy 的,用 git config --global --get http.proxy 检查。变量有值仍然超时,就到客户端里换一个节点。
SSL_ERROR_SYSCALL、Connection was reset、ECONNRESET
连接建立后中途被断开。常见原因是节点不稳定,或者大文件下载途中节点被自动切换。换一个稳定的节点再试;git 克隆大仓库时,可以先用 --depth 1 只拉最新版本,减少传输量。
Missing dependencies for SOCKS support
pip 等基于 Python 的工具在 all_proxy 是 socks5:// 开头时,需要额外的 SOCKS 支持库,没有装就会报这个错。最简单的办法是在这条命令里临时取消 all_proxy,只保留 http_proxy 和 https_proxy 两个 HTTP 地址。
kex_exchange_identification 或 SSH 连接 22 端口超时
SSH 方式访问 GitHub 时,22 端口在部分网络里不通。除了按上文给 SSH 配置代理,也可以让 SSH 改走 GitHub 提供的 443 端口:在 ~/.ssh/config 里把 github.com 的 HostName 写成 ssh.github.com,Port 写成 443。
Could not resolve host
域名解析失败。如果用的是 socks5://,域名在本机解析,可能被干扰,换成 socks5h:// 或改用 HTTP 代理地址;如果没设代理,先确认变量是否生效。
常见误区
- 「系统代理开了,终端自然就走代理」。 多数命令行工具不读系统代理,这是本文存在的原因。
- 「
localhost和127.0.0.1一样」。 大多数时候一样,但个别环境里localhost会被解析成 IPv6 地址,而客户端只监听 IPv4,结果连接被拒绝。写127.0.0.1更稳。 - 「环境变量设一次,以后都有效」。
export只对当前窗口有效,新开的标签页需要重新设置,或使用开关函数。 - 「全部流量都走代理才稳」。 环境变量会让国内镜像源、公司内网也绕到海外再回来,速度变慢还浪费流量。把这些域名写进
no_proxy,或者改用 TUN 加规则模式,让分流规则来决定哪些直连。 - 「设置越多越保险」。 同时开了 TUN 模式、环境变量和 git 的代理配置,流量可能被代理两次,出了问题也更难判断是哪一层的原因。选一种方式就够,换方式之前先把旧的设置清理干净。
各工具设置方式汇总
| 工具 | 是否读取环境变量 | 单独的设置方式 | 取消方式 |
|---|---|---|---|
| curl、wget | 是 | 命令前加变量,或用 -x 参数 | unset 对应变量 |
| git(HTTPS 地址) | 是 | git config --global http.proxy | git config --global --unset http.proxy |
| git(SSH 地址) | 否 | 在 ~/.ssh/config 里写 ProxyCommand | 删除对应配置 |
| npm | 是 | npm config set proxy 和 https-proxy | npm config delete |
| pip | 是 | --proxy 参数或 pip config set global.proxy | pip config unset global.proxy |
| docker 拉取镜像 | 否 | 需要给 Docker 守护进程单独配置代理 | 删除配置后重启服务 |
| ping | 否 | 不支持代理 | 不适用 |
Docker 需要单独说明:docker pull 是由后台的守护进程执行的,不继承你终端里的环境变量。需要在 Docker 的设置或服务配置里为守护进程指定代理,具体方式参照 Docker 的文档。
大致的做法分两种情况:
- Docker Desktop(macOS、Windows)。 在设置的资源或代理相关页面里填写手动代理地址,保存后会自动重启引擎。不同版本的菜单位置略有差异。
- Linux 上的 Docker 服务。 给 Docker 的系统服务加一个配置片段,在里面用
Environment=写上HTTPS_PROXY等变量,然后重新加载服务配置并重启 Docker。
还有一点容易踩坑:容器内部的 127.0.0.1 指的是容器自己,不是你的电脑。容器里的程序要用宿主机上的代理,Docker Desktop 下可以写 host.docker.internal 加端口,同时在代理客户端里打开允许局域网连接。
按场景选择设置方式
| 场景 | 推荐方式 | 理由 |
|---|---|---|
| 偶尔克隆仓库、装个依赖 | 临时 export 或单条命令前加变量 | 用完即失效,不留后遗症 |
| 每天在终端里开发 | 开关函数或 TUN 模式 | 一条命令切换,或者完全不用管 |
| 只有 GitHub 需要代理 | git 按域名设置代理 | 国内代码平台保持直连 |
| WSL2 | Windows 上开 TUN,或镜像网络模式 | 避开 WSL 网络地址的麻烦 |
| Docker 拉镜像 | 给守护进程配置代理,或用镜像加速 | 环境变量对守护进程无效 |
| AI 编程工具 | TUN 模式 | 子进程多,逐个配置容易漏 |
如果你通过 SSH 登录的是一台海外服务器,在服务器上执行命令本来就是从海外出去的,不需要设置任何代理,只有本机终端才需要。
用 TUN 模式一步到位
上面这些设置的共同缺点是要逐个工具配置,而且总有不读环境变量的程序。TUN 模式从网络层接管整台电脑的流量,终端里的任何命令都不需要设置就能走代理。
- 在代理客户端里打开 TUN 模式,首次开启需要授予管理员权限或安装服务。
- 取消之前设置的环境变量和各工具的代理配置,避免重复代理。
- 执行
curl -I https://www.google.com验证。
两种方式怎么选:
- 偶尔在终端里拉一次代码、装一次依赖,用环境变量,按需开关。
- 每天都在终端里工作,或者使用会在后台启动很多子进程的 AI 编程工具,用 TUN 模式更省心。这类工具的专门说明见AI 编程工具的网络设置。
TUN 模式的原理、开启步骤和副作用见系统代理和 TUN 模式的区别。使用 TUN 时保持规则模式即可,国内的镜像源和代码仓库仍然直连,分流的原理见规则模式和全局模式。
终端代理设置常见问题
终端代理怎么设置?
macOS 和 Linux 在终端执行 export https_proxy=http://127.0.0.1:端口 和对应的 http_proxy、all_proxy。Windows 的 PowerShell 用 $env:HTTPS_PROXY="http://127.0.0.1:端口",CMD 用 set https_proxy=http://127.0.0.1:端口。端口换成自己代理客户端显示的本地端口。
为什么开了代理终端还是连不上?
因为系统代理只对浏览器等读取系统设置的软件生效,命令行工具大多不读取它。需要另外设置代理环境变量,或者在代理客户端里开启 TUN 模式。
git 代理怎么设置和取消?
设置用 git config --global http.proxy http://127.0.0.1:端口,取消用 git config --global --unset http.proxy。这只对 HTTPS 方式的仓库地址有效,SSH 方式的地址需要在 SSH 配置里另外设置。
终端代理的端口应该填多少?
填你的代理客户端正在监听的本地端口,在客户端的设置页面可以看到。常见的有 7890、7897、10808 等,但不同软件和版本的默认值不同,不能照抄教程里的数字。
设置了代理为什么 ping 不通 Google?
ping 走的是 ICMP 协议,HTTP 和 SOCKS 代理都不处理这类流量,所以 ping 不通是正常的。验证终端代理应该用 curl -I https://www.google.com,看能否返回响应头。
怎么让终端代理永久生效?
可以把 export 语句写进 ~/.zshrc 或 ~/.bashrc,但不建议常开,因为代理客户端没运行时所有命令都会失败。更稳妥的是定义 proxy_on 和 proxy_off 两个函数按需切换,或者直接使用 TUN 模式。
命令行走代理会消耗很多机场流量吗?
取决于下载的内容。克隆大型仓库、拉取容器镜像、安装大量依赖都可能产生几个 GB 的流量。国内镜像源能提供的资源尽量走直连,日常用量的估算方法见机场流量多少够用。
git clone 提示 Failed to connect to github.com port 443 怎么办?
说明 git 没有走代理。在当前终端设置 https_proxy,或者执行 git config --global http.proxy http://127.0.0.1:端口。如果仓库地址是 git@github.com: 开头的 SSH 地址,上面的设置都不起作用,要单独配置 SSH,或者改用 HTTPS 地址。
GOPROXY 和终端代理是一回事吗?
不是。GOPROXY 指定的是从哪个模块镜像下载 Go 依赖,填的是镜像网址;终端代理指定的是网络请求经过哪个代理,填的是本机代理端口。用国内模块镜像时可以不开代理,两者互不替代。
公司电脑上终端代理不生效怎么办?
公司网络可能有自己的代理或安全软件,会和你的设置冲突。先看系统里是否已经存在 HTTP_PROXY 之类的变量,以及 git、npm 的全局配置里有没有公司预设的代理。工作设备是否允许使用个人代理,请先遵守公司的规定。