AI 与开发工具网络

终端代理设置教程:git 代理、npm 代理、pip、Docker 怎么走代理

更新于 · 约 18 分钟读完 · 登机口编辑整理

为什么终端不走系统代理

客户端里的「系统代理」开关,本质是往操作系统的网络设置里写了一条「HTTP 代理是本机某个端口」的记录。浏览器和一部分桌面软件会主动去读这条记录,于是它们的流量被送到客户端。

命令行程序不一样。git、npm、pip、curl 这些工具通常不看系统设置,它们只认两样东西:自己的配置文件,以及终端里的环境变量。所以系统代理开着,终端依然是直连,这是正常行为,不是客户端坏了。两种代理方式的区别可以看系统代理与 TUN 模式。

先确认本地代理端口

后面所有命令都要用到「本地代理地址」,格式是 127.0.0.1:端口。端口号因客户端和个人设置而不同,本文统一用 7890 举例,请以你自己客户端设置页显示的端口为准。

  1. 打开客户端的设置页,找到「端口」「混合端口」或类似名称的一项;
  2. 记下端口号。Clash 系客户端的混合端口同时支持 HTTP 和 SOCKS5 两种代理协议;
  3. 确认客户端正在运行,并且已经选好一个可用节点。

端口填错是终端代理不生效最常见的原因,报错一般是 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 是最容易搞混的,因为「拉镜像」「构建镜像」「容器运行」走的是三条不同的路。

  1. 拉镜像(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"
  1. 构建镜像(docker build): 构建过程里的 apt、npm install 运行在临时容器内,需要通过构建参数传入,例如 docker build --build-arg HTTP_PROXY=... --build-arg HTTPS_PROXY=... .。
  2. 容器运行时: 容器里的 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 的代理配置取消掉,避免客户端没开时这些工具报连接被拒绝。

如何取消所有代理设置

  1. 当前终端:macOS / Linux 执行 unset http_proxy https_proxy all_proxy;PowerShell 执行 Remove-Item Env:HTTP_PROXY 和 Remove-Item Env:HTTPS_PROXY;
  2. git:git config --global --unset http.proxy;
  3. npm:npm config delete proxy 和 npm config delete https-proxy;
  4. pip:pip config unset global.proxy;
  5. 检查 ~/.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 的命令容易出错。

  1. 每种终端的环境变量互不相通。 在 PowerShell 里用 $env: 设置的变量,只在这个 PowerShell 窗口里有效,另开一个命令提示符或 Git Bash 窗口是看不到的。在哪个终端里跑命令,就在哪个终端里设置;
  2. Git Bash 用的是 bash 的写法。 在 Git Bash 里要用 export http_proxy=...,而不是 set 或 $env:;
  3. PowerShell 里的 curl 可能不是真正的 curl。 在系统自带的 Windows PowerShell 里,curl 是另一个命令的别名,参数和输出都不一样。验证代理时写成 curl.exe -I https://www.google.com,调用的才是 curl 本体;
  4. 想让 PowerShell 每次打开都带上代理, 把设置的那两行写进 PowerShell 的配置文件,路径可以用 $PROFILE 查看。和 macOS 一样,更推荐写成两个函数按需开关,而不是永久生效;
  5. 命令提示符取消代理的写法是把变量设为空, 即 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日,未经本站实测,购买前请以官网为准。整理方法见这里。

接着读