终端代理设置教程:git 代理、npm 代理、pip、Docker 怎么走代理
为什么终端不走系统代理
客户端里的「系统代理」开关,本质是往操作系统的网络设置里写了一条「HTTP 代理是本机某个端口」的记录。浏览器和一部分桌面软件会主动去读这条记录,于是它们的流量被送到客户端。
命令行程序不一样。git、npm、pip、curl 这些工具通常不看系统设置,它们只认两样东西:自己的配置文件,以及终端里的环境变量。所以系统代理开着,终端依然是直连,这是正常行为,不是客户端坏了。两种代理方式的区别可以看系统代理与 TUN 模式。
先确认本地代理端口
后面所有命令都要用到「本地代理地址」,格式是 127.0.0.1:端口。端口号因客户端和个人设置而不同,本文统一用 7890 举例,请以你自己客户端设置页显示的端口为准。
- 打开客户端的设置页,找到「端口」「混合端口」或类似名称的一项;
- 记下端口号。Clash 系客户端的混合端口同时支持 HTTP 和 SOCKS5 两种代理协议;
- 确认客户端正在运行,并且已经选好一个可用节点。
端口填错是终端代理不生效最常见的原因,报错一般是 Connection refused。
用环境变量给当前终端设置代理
环境变量只对当前这个终端窗口生效,关掉窗口就没了,适合临时使用。
macOS / Linux(bash、zsh):
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
Windows PowerShell:
$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
Windows 命令提示符(cmd):
set HTTP_PROXY=http://127.0.0.1:7890
set HTTPS_PROXY=http://127.0.0.1:7890
几个容易踩的细节:
https_proxy的值仍然写http://开头。这个变量的意思是「访问 HTTPS 网站时用哪个代理」,而本地代理本身是一个 HTTP 代理。- macOS 和 Linux 的环境变量区分大小写。多数工具大小写都认,但 curl 只认小写的
http_proxy。拿不准时大小写各设一份。 sudo默认不继承环境变量,sudo apt update这类命令不会走代理,需要用sudo -E保留环境变量。- 设置之后想让本机地址和内网地址不走代理,可以再加一行
export no_proxy=localhost,127.0.0.1。
如果经常要用,可以把开关写进 ~/.zshrc 或 ~/.bashrc:
proxy_on() {
export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
}
proxy_off() {
unset http_proxy https_proxy all_proxy
}
保存后重新打开终端,需要时输入 proxy_on,不需要时输入 proxy_off。
给各个工具单独设置代理
不想影响整个终端,可以只给某个工具配置。下面的配置会写进工具自己的配置文件,长期有效,直到你取消。
| 工具 | 设置代理 | 取消代理 |
|---|---|---|
| git | git config --global http.proxy http://127.0.0.1:7890 |
git config --global --unset http.proxy |
| 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 |
| pip | pip config set global.proxy http://127.0.0.1:7890 |
pip config unset global.proxy |
| curl | 单次使用:curl -x http://127.0.0.1:7890 网址 |
不加 -x 即可 |
补充说明:
- git:
http.proxy这一项同时管http://和https://两种仓库地址。它对git@github.com:开头的 SSH 地址无效,SSH 的处理方法见 GitHub 访问慢与 git clone 失败。 - npm: yarn、pnpm 一般也会读取环境变量,各自的配置项名称以官方文档为准。
- pip: 只想临时用一次,可以写成
pip install --proxy http://127.0.0.1:7890 包名。 - curl: curl 会自动读取环境变量,设置过
http_proxy和https_proxy就不用再加-x。
Docker 要分三种情况
Docker 是最容易搞混的,因为「拉镜像」「构建镜像」「容器运行」走的是三条不同的路。
- 拉镜像(docker pull): 真正去下载的是 Docker 守护进程,不是你敲命令的终端,所以终端里的环境变量对它无效。使用 Docker Desktop 的,在它的设置里找到代理相关选项填入本地代理地址。Linux 上用 systemd 管理 Docker 的,新建
/etc/systemd/system/docker.service.d/http-proxy.conf,内容如下,然后执行sudo systemctl daemon-reload和sudo systemctl restart docker:
[Service]
Environment="HTTP_PROXY=http://127.0.0.1:7890"
Environment="HTTPS_PROXY=http://127.0.0.1:7890"
Environment="NO_PROXY=localhost,127.0.0.1"
- 构建镜像(docker build): 构建过程里的
apt、npm install运行在临时容器内,需要通过构建参数传入,例如docker build --build-arg HTTP_PROXY=... --build-arg HTTPS_PROXY=... .。 - 容器运行时: 容器里的
127.0.0.1指的是容器自己,不是你的电脑。要让容器访问宿主机上的代理,得用宿主机的地址(Docker Desktop 提供host.docker.internal这个名字),并且在客户端里打开「允许局域网连接」。
嫌麻烦的话,Docker 场景更适合直接用 TUN 模式。
WSL2 的情况和容器类似:在默认的网络模式下,127.0.0.1 指的是 Linux 子系统自己,不是 Windows。想用 Windows 上的代理,要填 Windows 主机在虚拟网络里的地址,并在客户端打开「允许局域网连接」;或者直接在 Windows 上开 TUN 模式。
怎么验证代理生效了
用 curl 请求一个需要代理才能访问的网站,看有没有返回响应头:
curl -I https://www.google.com
返回 HTTP/2 200 或其他状态码,说明流量已经走代理。一直卡住直到超时,说明没走上。
如果马上返回 Connection refused,是端口不对或客户端没有运行;如果等了很久才超时,多半是当前节点不可用,换一个节点再试。
不要用 ping 测试。ping 使用的是 ICMP 协议,HTTP 和 SOCKS 代理都不转发它,所以设置了代理 ping 不通是正常的,不能说明代理没生效。
TUN 模式:不想逐个配置时的办法
TUN 模式会在系统里创建一张虚拟网卡,把所有程序的流量都接管过来,再按规则决定直连还是走代理。打开之后,终端、Docker、各种桌面软件都不需要单独设置。
它的代价是:首次开启需要管理员权限或安装服务,和其他 VPN 类软件可能冲突,规则写得不好时国内流量也可能绕路。日常开发的建议是:偶尔用用就设环境变量,长期在终端里干活就开 TUN。开启方法见 Clash Verge Rev 使用教程,规则相关的内容见规则分流。
开了 TUN 之后,建议把之前写进 git、npm 的代理配置取消掉,避免客户端没开时这些工具报连接被拒绝。
如何取消所有代理设置
- 当前终端:macOS / Linux 执行
unset http_proxy https_proxy all_proxy;PowerShell 执行Remove-Item Env:HTTP_PROXY和Remove-Item Env:HTTPS_PROXY; - git:
git config --global --unset http.proxy; - npm:
npm config delete proxy和npm config delete https-proxy; - pip:
pip config unset global.proxy; - 检查
~/.zshrc、~/.bashrc里有没有写死的export行,有就删掉。
想知道 git 当前有没有代理配置,可以执行 git config --global --get http.proxy,没有输出就是没设置。
更多工具的代理写法
除了 git、npm、pip 和 curl,开发时常用的其他工具对代理的支持方式各不相同。下表按「是否读取环境变量」分一下,读取的不用单独配置,不读取的才需要另外设置。
| 工具 | 是否读取环境变量 | 单独设置的方法 |
|---|---|---|
| wget | 读取 http_proxy、https_proxy |
一般不需要 |
| Homebrew | 读取,内部调用的是 curl 和 git | 一般不需要 |
| go(下载模块) | 读取 HTTP_PROXY、HTTPS_PROXY |
一般不需要 |
| cargo | 读取 http_proxy、https_proxy |
也可以在 cargo 的配置文件里写 [http] 段的 proxy 项 |
| conda | 读取 | conda config --set proxy_servers.http http://127.0.0.1:7890,https 同理 |
| apt | sudo 默认不传环境变量 |
在 /etc/apt/apt.conf.d/ 下新建配置文件,写入 Acquire::http::Proxy "http://127.0.0.1:7890"; |
| ssh | 不读取 | 在 ~/.ssh/config 里用 ProxyCommand 指定,见 GitHub 访问慢 |
有两处常被弄混:
- Go 的
GOPROXY不是网络代理。 它指定的是模块的下载镜像站,和HTTP_PROXY是两回事。设了国内的模块镜像,很多时候就不需要再走代理; - 用 Node.js、Python 等写的程序不一定读环境变量。 环境变量只是一种约定,程序是否遵守取决于它用的网络库和作者的实现。某个命令行工具设了环境变量仍然超时,先查它的文档里有没有自己的代理选项,没有的话用 TUN 模式。
另外一个思路是不走代理。npm、pip、cargo、apt 等都有国内镜像源,换成镜像源后下载速度通常比走代理更快,也不消耗机场流量。代理留给没有镜像的场景,比如访问代码托管平台、拉取托管在境外的私有依赖。
让一部分地址不走代理
环境变量一旦设置,终端里所有请求都会交给代理。访问本机服务、内网地址、公司的私有仓库时,这反而会出问题。no_proxy 变量用来列出不走代理的地址:
export no_proxy=localhost,127.0.0.1,::1,.internal.example.com
写法上注意三点:多个条目用英文逗号分隔,中间不要加空格;域名前面加一个点表示匹配它的所有子域名;不同工具对 IP 段、通配符的支持不一致,最稳妥的是把要用到的地址逐个写全。大小写两个版本(no_proxy 和 NO_PROXY)最好都设。
git 可以做得更细,只给某一个站点设置代理,其余仓库保持直连:
git config --global http.https://github.com.proxy http://127.0.0.1:7890
这条配置只对 https://github.com 开头的仓库地址生效。公司内网的仓库、国内的代码托管平台不受影响,比全局的 http.proxy 更适合同时使用多个代码源的人。取消时执行 git config --global --unset http.https://github.com.proxy。
Windows 终端的几个差别
Windows 上有命令提示符、PowerShell、Git Bash、WSL 几种终端,写法和行为都不同,照搬 macOS 的命令容易出错。
- 每种终端的环境变量互不相通。 在 PowerShell 里用
$env:设置的变量,只在这个 PowerShell 窗口里有效,另开一个命令提示符或 Git Bash 窗口是看不到的。在哪个终端里跑命令,就在哪个终端里设置; - Git Bash 用的是 bash 的写法。 在 Git Bash 里要用
export http_proxy=...,而不是set或$env:; - PowerShell 里的
curl可能不是真正的 curl。 在系统自带的 Windows PowerShell 里,curl是另一个命令的别名,参数和输出都不一样。验证代理时写成curl.exe -I https://www.google.com,调用的才是 curl 本体; - 想让 PowerShell 每次打开都带上代理, 把设置的那两行写进 PowerShell 的配置文件,路径可以用
$PROFILE查看。和 macOS 一样,更推荐写成两个函数按需开关,而不是永久生效; - 命令提示符取消代理的写法是把变量设为空, 即
set HTTP_PROXY=和set HTTPS_PROXY=,等号后面什么都不写。
常见问题
设置了环境变量,为什么 git 还是连不上?
先看仓库地址。如果是 git@github.com: 开头的 SSH 地址,环境变量和 http.proxy 都不管用,要么改用 HTTPS 地址,要么给 SSH 单独配置代理。如果是 HTTPS 地址仍然失败,检查端口号是否和客户端一致、客户端是否在运行、当前节点是否可用。
用 socks5 还是 http 代理更好?
对日常开发没有明显差别,HTTP 代理兼容性最好,几乎所有工具都支持。需要用 SOCKS5 时,建议写成 socks5h://,多出来的 h 表示域名交给代理去解析,可以避免本地 DNS 解析出错误结果。
关掉客户端后终端报 Connection refused 怎么办?
这是因为代理配置还在,但本地端口已经没有程序在监听。按上面「如何取消所有代理设置」一节逐项清除即可。这也是只在需要时临时设置环境变量的好处:关掉终端窗口,设置自动消失。
设置 all_proxy 之后 pip 报缺少 SOCKS 依赖怎么办?
这是因为 all_proxy 的值是 socks5:// 开头的地址,而 pip 所用的网络库默认没有安装 SOCKS 支持。最简单的处理是取消这个变量,执行 unset all_proxy,只保留 http_proxy 和 https_proxy 两项,它们指向的是 HTTP 代理,不需要额外依赖。Clash 系客户端的混合端口同时支持两种协议,只用 HTTP 的写法就够了。
能不能只让 GitHub 走代理,其他仓库直连?
可以。git 支持按站点设置代理,执行 git config --global http.https://github.com.proxy http://127.0.0.1:7890 之后,只有 GitHub 的 HTTPS 仓库走代理,其他地址保持直连。前提是没有设置全局的 http.proxy,也没有在终端里设置代理环境变量,否则其他仓库仍然会走代理。
环境变量和工具自己的配置同时存在,以哪个为准?
一般是越具体的越优先:命令行参数高于工具自己的配置文件,配置文件高于环境变量。比如 git 设了 http.proxy 之后,就不再看环境变量。排查时要把这几层都检查一遍,常见的情况是环境变量已经取消,工具配置里还留着一个旧端口。
公司电脑能这样设置吗?
公司网络通常有自己的代理和安全策略,私自更改可能违反公司规定。在公司设备上请先了解并遵守所在单位的网络使用要求。
接下来看什么
终端代理配好之后,命令行里的 AI 编程工具也就能连上了,长任务断连的处理见命令行 AI 工具的网络设置。还没有机场的话,可以先看机场对比表。
本文中的套餐与价格整理自公开资料,核对日期为 2026年11月14日,未经本站实测,购买前请以官网为准。整理方法见这里。
接着读
ChatGPT 反复验证、Too Many Requests 原因:网络角度解释
从网络角度解释 ChatGPT 反复验证、Too Many Requests 的原因:共享 IP 请求密集、IP 频繁切换、数据中心 IP 信誉等,并说明固定节点、换同地区节点、减少并发等做法,账号与地区政策以官方为准。
Claude Code 代理设置、Codex CLI 代理:TUN 与长任务断连
Claude Code 代理设置、Codex CLI 代理都依赖终端网络环境:本文讲代理环境变量与 TUN 模式两种方案,长任务中节点切换导致断连的处理方法,以及企业网络与证书问题的一般思路。
Cursor 代理设置教程:Cursor 连接失败、对话中断的原因与排查顺序
Cursor 代理设置与 Cursor 连接失败排查:如何在设置里配置 http.proxy,什么时候改用 TUN 模式,长连接为什么会被节点自动切换打断,并给出一套从易到难的排查顺序。
Docker 代理设置教程:拉取镜像、构建镜像、容器内三种情况分别怎么配
Docker 代理设置分三种场景:docker pull 超时要给守护进程配代理,构建镜像时用 build-arg 传入,容器运行时用环境变量或 config.json。附各场景命令与 127.0.0.1 不通的原因。