引言:为什么包管理器需要自己的代理设置

你肯定遇到过这种情况:终端里已经导出了 http_proxy 和 https_proxy 变量,curl 能顺利下载网页,但 npm install 却卡住一分钟然后报错 ETIMEDOUT。或者 apt update 默默尝试直连镜像源,好像根本不存在代理一样。又或者 Docker 在构建镜像时无法拉取基础层,但同一个终端里 docker pull 却正常。这不是 bug,也不是玄学。只是每个工具读取网络设置的方式不同,环境变量只能部分覆盖。

本指南专门讲解五个开发者必备工具的专属配置文件:npm(.npmrc 文件)、pip(pip.conf 或 pip.ini)、apt(apt.conf.d 目录)、Docker(daemon.json 和 config.json)以及 git(git config)。我们特意不重复终端和 CI 中环境变量的内容。这里的目标不同:展示如何配置代理,使其始终生效,无论谁从何处运行命令。

最终你将获得五份可直接复制到任何机器的可用配置,理解每个工具查找设置的位置,以及一套验证命令。此外,你还将知道如何快速回滚所有更改。

本指南适合谁

  • 工作笔记本或服务器位于企业或家庭代理后的开发者。
  • 需要构建流量经过指定代理地址的测试和自动化工程师。
  • 配置标准工作站镜像的管理员。
  • 所有使用租用代理(包括移动代理)进行开发,并希望只有特定工具而非整个系统走代理的人。

需要提前了解的知识

基本的终端操作能力即可:打开控制台、切换目录、编辑文本文件。我们将使用 Linux 的 nano 编辑器和 Windows 的记事本,但任何编辑器都可以。了解 IP 地址和端口也有帮助,不过我们会在概念部分回顾基础知识。

预计需要多长时间

如果依次配置全部五个工具,请预留 60 到 90 分钟。每个工具连同验证需要 10-15 分钟。最耗时的环节是 Docker,因为它有两个配置层级且需要重启服务。

准备工作

在修改配置之前,先收集所有必要信息。跳过这一步是之后花数小时猜测错误所在的主要原因。

所需的代理信息

你需要四个参数。把它们记录在文本文件中,避免翻找聊天记录:

  • 代理类型:HTTP 或 HTTPS(有时是 SOCKS5,但大多数包管理器需要 HTTP 代理)。
  • 地址:域名或 IP,例如 proxy.corp.local 或 10.20.30.40。
  • 端口:通常是 3128、8080 或 8888。
  • 登录名和密码(如果代理需要认证)。注意密码中的特殊字符:它们需要编码,详见下文。

系统要求和版本

本指南已在 2026 年的最新版本上验证,适用于:

  • Ubuntu 22.04 和 24.04、Debian 12 和 13(用于 apt)。
  • Node.js 20 和 22,npm 10 和 11。
  • Python 3.10 及以上,pip 24 及以上。
  • Docker Engine 25 及以上(daemon.json 中的 proxies 键在版本 23 中引入,更早版本请使用 systemd drop-in,我们将展示两种方式)。
  • Git 2.40 及以上。

如果你使用 Windows,npm、pip 和 git 的所有命令在 PowerShell 中均可直接使用,只是文件路径不同。Docker Desktop 的代理设置通过图形界面完成,我们也会介绍。

访问权限

npm、pip 和 git 使用普通用户权限即可:它们的配置位于主目录中。apt 和 Docker 需要 sudo,因为文件位于 /etc 中并改变系统服务的行为。

备份

开始之前复制现有配置。每个文件一条命令,你随时都能恢复到原始状态:

cp ~/.npmrc ~/.npmrc.bak 2>/dev/null; cp ~/.config/pip/pip.conf ~/pip.conf.bak 2>/dev/null; cp ~/.gitconfig ~/.gitconfig.bak 2>/dev/null; sudo cp /etc/docker/daemon.json /etc/docker/daemon.json.bak 2>/dev/null; sudo cp -r /etc/apt/apt.conf.d /etc/apt/apt.conf.d.bak 2>/dev/null

末尾的 2>/dev/null 用于在文件不存在时不报错。这很正常:许多用户的 .npmrc 和 pip.conf 初始并不存在。

建议:在主目录中创建 proxy-configs 文件夹,把五份配置的基准版本放在那里。迁移到新机器只需复制五个文件。

基础概念:为什么环境变量不够用

先了解底层原理,否则后续步骤看起来就像一串魔法咒语。

包管理器语境下的代理是什么

代理服务器是中间人。你的 npm 不直接连接 registry.npmjs.org,而是连接代理并请求它访问 registry.npmjs.org。对于 HTTPS 资源使用 CONNECT 方法:代理建立隧道,加密流量不经解密穿过。包管理器需要知道代理地址、端口以及必要时的凭据。

工具如何发现代理

存在三个配置层级,它们构成优先级链:

  1. 命令行标志:例如 pip install --proxy。仅对单次运行生效。
  2. 工具自有配置:.npmrc、pip.conf 等。对该工具始终生效。
  3. 环境变量:http_proxy、https_proxy、no_proxy。对当前会话中读取它们的所有程序生效。

关键词是读取它们的。问题就从这里开始。

环境变量不够用的四个原因

原因一:切换用户。当你运行 sudo apt update 时,命令以 root 身份执行,而 sudo 默认会清空环境(env_reset 选项)。你的 http_proxy 留在普通用户那里。更重要的是,apt 本身以服务用户 _apt 下载文件,它根本没有你的会话。

原因二:守护进程和服务。Docker Engine 是 systemd 在系统启动时启动的后台服务。它从未见过你的终端。docker pull 命令只是向守护进程发送请求,下载镜像的是守护进程。因此你控制台中的变量对 docker pull 完全没有影响。

原因三:理解不同。有些程序只读小写的 http_proxy,有些只读大写的 HTTP_PROXY,还有些两者都读。旧版 npm 忽略 no_proxy。有些工具不理解变量中的凭据。自有配置免去了猜测。

原因四:粒度。环境变量要么有要么没有。而你可能需要只把 github.com 走代理,内部 GitLab 不走。或者通过代理访问公共 PyPI,直连内部索引。这类规则只有配置文件才能实现:git 支持为特定 URL 配置代理,apt 支持特定主机,Docker 支持守护进程级别的排除列表。

密码中特殊字符的编码

配置中的登录名和密码以 URL 形式传递:http://user:password@host:port。密码中的 @、:、/、#、?、% 和空格会破坏地址解析。需要替换为百分号编码:@ 变为 %40,: 变为 %3A,# 变为 %23,/ 变为 %2F,% 变为 %25,空格变为 %20。例如密码 p@ss:1 在配置中写作 p%40ss%3A1。记住这条规则,它在所有五个工具中都能救你。

第 1 步:验证代理并准备基准字符串

本阶段目标:确认代理确实可用,并获得一条经过验证的连接字符串,用于插入所有配置。

  1. 打开终端。Linux 中按 Ctrl+Alt+T,Windows 中从开始菜单打开 PowerShell。
  2. 按模板组装连接字符串 http://登录名:密码@地址:端口。无认证则用 http://地址:端口。示例:http://dev:s3cret@10.20.30.40:3128。
  3. 使用 curl 并通过 -x 标志显式指定代理执行测试请求,避免依赖环境变量:
    curl -x http://dev:s3cret@10.20.30.40:3128 -I https://registry.npmjs.org/
  4. 等待响应。应以 HTTP/2 200 或 HTTP/1.1 200 OK 开头。如果看到 407 Proxy Authentication Required,说明登录名或密码错误。如果显示 Could not resolve proxy,说明地址拼写错误。如果显示 connection refused,说明端口错误或代理未开启。
  5. 对其他目标重复验证:https://pypi.org/simple/、https://deb.debian.org/、https://registry-1.docker.io/v2/、https://github.com/。Docker 返回 401 是正常的,说明已到达镜像仓库,它在请求令牌。
  6. 把最终字符串记入你的文本文件。这就是你的基准代理字符串。

注意:如果密码包含特殊字符,就在这一步编码并通过 curl 验证编码后的版本。这样后续所有配置中你插入的都是已验证可用的字符串。

建议:如果提供商给你的不是单个代理,而是地址池或带 IP 轮换的移动代理,通常会有统一的入口点:一个主机和端口,IP 在其后自动切换。请在配置中写入这个入口点,而不是池中的具体 IP,否则第一次轮换时配置就会失效。

验证:curl 带 -x 标志对全部五个地址返回 200 状态码(Docker Hub 为 401)。如果有一个不响应,不要继续:配置无法修复不工作的代理。

第 2 步:通过 .npmrc 文件配置 npm

本阶段目标:npm install、npm view 和 npm publish 在任何项目和任何控制台(包括自行运行 npm 的开发环境)中都通过代理工作。

npm 配置文件的存放位置

npm 按优先级递增顺序从多个文件读取设置:内置值、npm 安装目录中的全局文件、用户级 ~/.npmrc(Windows 中为 C:\Users\用户名\.npmrc)以及项目根目录中 package.json 旁边的项目级 .npmrc。代理几乎总是使用用户级文件:它应用于所有项目,但不会进入仓库。

分步配置

  1. 为普通 HTTP 流量设置代理:
    npm config set proxy http://dev:s3cret@10.20.30.40:3128
  2. 为 HTTPS 流量设置代理(npm 仓库通过 HTTPS 工作,因此这项设置最重要):
    npm config set https-proxy http://dev:s3cret@10.20.30.40:3128
    注意:值以 http:// 开头,而不是 https://。这是代理本身的地址,它通常以普通 HTTP 接受连接,即使隧道传输 HTTPS。
  3. 如果有需要直连的内部仓库或镜像,用逗号添加排除项:
    npm config set noproxy localhost,127.0.0.1,.corp.local
    域名前的点表示所有子域名。
  4. 打开文件确认已写入:
    cat ~/.npmrc
    Windows 中:type $env:USERPROFILE\.npmrc。你应该看到三行键=值格式的内容。
  5. 如果企业代理替换了证书,添加公司根证书:
    npm config set cafile /etc/ssl/certs/corp-root.pem
    非必要不要通过 strict-ssl=false 禁用证书检查:这会为包替换打开通道。

另一种方式是手动创建文件。~/.npmrc 内容如下:

proxy=http://dev:s3cret@10.20.30.40:3128 https-proxy=http://dev:s3cret@10.20.30.40:3128 noproxy=localhost,127.0.0.1,.corp.local

每对应在不同行。等号两边不要加引号和空格。

yarn 和 pnpm 怎么办

Yarn Classic(1.x)读取同一个 ~/.npmrc,另外还读取自己的 ~/.yarnrc,使用 proxy 和 https-proxy 键。Yarn Berry(2+)将设置存储在 .yarnrc.yml 中:使用 httpProxy 和 httpsProxy 键。pnpm 完全兼容 .npmrc,无需额外操作。还要记住,npm ci 和企业 IDE 以同一用户运行 npm,因此用户级 .npmrc 也覆盖它们。

建议:命令 npm config list --json 显示考虑所有文件后的最终配置。如果看到 proxy=null,说明文件未被读取:检查它是否位于你运行 npm 的用户的主目录中。

验证:执行 npm view lodash version。1-3 秒后应返回版本号字符串。为更直观,可临时取消环境变量(unset http_proxy https_proxy)后重复:npm 仍应工作,因为它读取 .npmrc。

可能的问题

  • ETIMEDOUT 或 ECONNRESET:代理地址或端口错误,或代理阻止到 443 端口的 CONNECT。通过 curl 检查基准字符串。
  • 407 Proxy Authentication Required:登录名或密码错误,通常是特殊字符未编码。
  • UNABLE_TO_GET_ISSUER_CERT_LOCALLY:代理替换证书,需要带企业根证书的 cafile。

第 3 步:通过 pip.conf 配置 pip

本阶段目标:pip install 和 pip download 通过代理工作,包括在虚拟环境中和从 Python 脚本启动时。

pip.conf 的位置

pip 使用三个层级的文件:全局(全系统)、用户级和虚拟环境级。路径取决于系统:

  • Linux 用户级:~/.config/pip/pip.conf(旧版 ~/.pip/pip.conf 也会读取)。
  • Linux 全局:/etc/pip.conf。
  • macOS 用户级:~/Library/Application Support/pip/pip.conf,若该文件夹不存在则用 ~/.config/pip/pip.conf。
  • Windows 用户级:%APPDATA%\pip\pip.ini,即 C:\Users\用户名\AppData\Roaming\pip\pip.ini。
  • 虚拟环境内:pip.conf(或 pip.ini)直接放在 venv 目录根下。

不想猜就问问 pip 本身:命令 pip config debug 会输出它检查的所有路径并标记存在的文件。

分步配置

  1. 确认 pip 是最新的:pip --version。应为 24 或更高版本。
  2. 用一条命令设置代理,pip 会在正确位置自动创建文件:
    pip config set global.proxy http://dev:s3cret@10.20.30.40:3128
    这里的 global 表示文件中的 [global] 节,而非系统级。创建的是用户级文件。
  3. 如果代理替换证书,指定根证书:
    pip config set global.cert /etc/ssl/certs/corp-root.pem
  4. 查看结果:
    pip config list
    预期输出:global.proxy='http://dev:s3cret@10.20.30.40:3128'。
  5. 打开文件检查格式。应如下所示:
    [global] proxy = http://dev:s3cret@10.20.30.40:3128 cert = /etc/ssl/certs/corp-root.pem
    每行一条,节名在上方方括号中。

pip 与 npm 的重要区别:pip 没有单独的 HTTPS 代理设置。一个 proxy 键用于所有连接。pip 配置中也没有 noproxy 的直接对应项:排除项只从环境变量 no_proxy 获取。如果需要直连内部索引,更简单的方法是为其指定单独的 index-url 并在该情况下以空 --proxy 值运行 pip,或在 venv 内使用不含 proxy 行的项目级 pip.conf。

建议:如果有多个项目,一个需要代理另一个不需要,将 pip.conf 放在对应虚拟环境的根目录中。venv 设置优先于用户级设置,无需切换全局文件即可获得不同行为。

注意:不要添加 trusted-host = pypi.org 来压制证书错误。这会禁用真实性检查,允许任何中间人向你提供伪造的包。正确做法是使用带企业证书的 cert 键。

验证:执行 pip download requests --no-deps -d /tmp/piptest。几秒后目录中会出现 requests-*.whl 文件。然后删除测试目录。如果想确认是配置文件在起作用,取消环境变量后重复。

可能的问题

  • ProxyError 或 Cannot connect to proxy:地址拼写错误或端口错误。对照基准字符串。
  • Tunnel connection failed: 407:认证错误。检查密码编码。
  • SSLError CERTIFICATE_VERIFY_FAILED:需要带代理根证书的 cert 键。
  • 文件已写入但 pip 看不到:你运行的是另一个解释器的 pip(例如用 python3 -m pip 调用了另一个 Python)。用你实际安装包时使用的命令执行 pip config debug。

第 4 步:通过 apt.conf.d 目录配置 apt

本阶段目标:sudo apt update 和 sudo apt install 通过代理下载包,而访问内部镜像走直连。

为什么是 apt.conf.d

apt 从 /etc/apt/apt.conf 和 /etc/apt/apt.conf.d/ 目录中的所有文件按字母顺序读取设置。良好做法是不动他人的文件,而是创建带数字前缀的自有文件。数字决定读取顺序:80proxy 文件会在 01autoremove 等系统文件之后应用。这样设置能经受 apt 包的任何更新。

分步配置

  1. 创建新的配置文件:
    sudo nano /etc/apt/apt.conf.d/80proxy
    会打开空编辑器。
  2. 为 HTTP 和 HTTPS 仓库写入两行。注意引号和分号——apt 语法中它们是必需的:
    Acquire::http::Proxy "http://dev:s3cret@10.20.30.40:3128"; Acquire::https::Proxy "http://dev:s3cret@10.20.30.40:3128";
  3. 如果有不需要代理的内部镜像,添加排除行。大写单词 DIRECT 表示直连:
    Acquire::http::Proxy::mirror.corp.local "DIRECT";
  4. 保存文件:nano 中按 Ctrl+O,然后 Enter,然后 Ctrl+X 退出。
  5. 限制文件权限,因为其中有密码:
    sudo chmod 600 /etc/apt/apt.conf.d/80proxy
    只有 root 能读取内容。
  6. 确认 apt 无语法错误地解析了文件:
    apt-config dump | grep -i proxy
    你应该看到带有自己值的 Acquire::http::Proxy 和 Acquire::https::Proxy 行。

以下是完整的文件示例供参考:

Acquire::http::Proxy "http://dev:s3cret@10.20.30.40:3128"; Acquire::https::Proxy "http://dev:s3cret@10.20.30.40:3128"; Acquire::http::Proxy::mirror.corp.local "DIRECT"; Acquire::https::Proxy::mirror.corp.local "DIRECT";

无需文件的单次运行替代方案:sudo apt -o Acquire::http::Proxy="http://10.20.30.40:3128" update。-o 标志便于在写入配置前测试值。

建议:自行缓存 deb 包的代理服务器通常有单独的 apt 端口。向管理员确认:如果有,apt update 会因本地缓存而快数倍。

验证:执行 sudo apt update。输出中会出现带仓库地址的 Hit 或 Get 行,不会有 Err 行。注意我们没有设置环境变量,sudo 无论如何都会清空它们,而 apt 仍能访问网络。这就是自有配置的效果。

可能的问题

  • Err: 407 Proxy Authentication Required:认证失败,检查特殊字符编码。
  • Could not connect 或 Connection timed out:apt 走了直连。很可能是文件中有拼写错误而 apt-config dump 未显示。检查 Acquire 的大小写和双冒号。
  • E: Syntax error:行尾缺少分号或引号。
  • 文件存在但 DIRECT 排除不生效:确保排除行中的主机名与 sources.list 中的名称逐字母匹配,不含 http:// 和端口。

第 5 步:在两个层级配置 Docker

本阶段目标:docker pull、docker build 和 docker compose pull 通过代理下载镜像,容器在需要时自动获得代理设置。

两个常被混淆的层级

Docker 有两个独立的地方需要不同的代理配置:

  • 守护进程层(dockerd 服务)。正是它从仓库下载镜像。在 /etc/docker/daemon.json 中或通过 systemd 配置。需要重启服务。
  • 客户端层(~/.docker/config.json 文件)。它不影响镜像下载。但它会自动将代理变量传入启动的容器和构建过程,使容器内的 apt 或 pip 也能看到代理。

只配置客户端——docker pull 不工作。只配置守护进程——镜像能下载,但 Dockerfile 中的 RUN apt-get update 会失败。两者都需要。

部分 A:通过 daemon.json 配置守护进程

  1. 检查版本:docker version。如果服务器版本为 23.0 或更新,使用 daemon.json。更早则跳到部分 B。
  2. 打开守护进程配置文件:
    sudo nano /etc/docker/daemon.json
    如果文件已存在且包含其他键,在同一对花括号内用逗号添加 proxies 块。如果文件不存在,从零创建。
  3. 写入设置块:
    { "proxies": { "http-proxy": "http://dev:s3cret@10.20.30.40:3128", "https-proxy": "http://dev:s3cret@10.20.30.40:3128", "no-proxy": "localhost,127.0.0.0/8,registry.corp.local" } }
    注意:键名用连字符且小写,必须这样写。这是守护进程的格式,客户端的键名不同。
  4. 保存文件(Ctrl+O、Enter、Ctrl+X)。
  5. 验证 JSON 有效,否则守护进程无法启动:
    python3 -m json.tool /etc/docker/daemon.json
    如果命令带缩进输出了文件内容——语法正确。如果报 Expecting value 或 Extra data——查找多余或缺失的逗号。
  6. 重启服务:
    sudo systemctl restart docker
    重启需要 5-15 秒。所有运行中的容器会停止,因此请在空闲时进行。
  7. 确认守护进程已启动:sudo systemctl status docker。应显示绿色的 active (running)。

注意:daemon.json 中多一个逗号——Docker 就完全无法启动,机器上所有容器随之崩溃。重启前务必通过 json.tool 检查文件并保留备份。

部分 B:通过 systemd 配置守护进程(适用于旧版本和作为替代)

  1. 创建服务附加设置目录:sudo mkdir -p /etc/systemd/system/docker.service.d
  2. 创建文件:sudo nano /etc/systemd/system/docker.service.d/http-proxy.conf
  3. 写入:
    [Service] Environment="HTTP_PROXY=http://dev:s3cret@10.20.30.40:3128" Environment="HTTPS_PROXY=http://dev:s3cret@10.20.30.40:3128" Environment="NO_PROXY=localhost,127.0.0.0/8,registry.corp.local"
  4. 保存并应用:sudo systemctl daemon-reload,然后 sudo systemctl restart docker。

是的,这里使用了环境变量,但它们不是在你的控制台中设置的,而是在服务定义中:守护进程在启动时从 systemd 获得它们。这是 Docker 23 之前版本的唯一方法。如果同时设置了 daemon.json 和 systemd 文件,daemon.json 优先。

部分 C:通过 ~/.docker/config.json 配置客户端

  1. 打开或创建文件 nano ~/.docker/config.json。如果文件已包含带仓库登录信息的 auths 块,不要删除它,用逗号在旁边添加新块。
  2. 写入:
    { "proxies": { "default": { "httpProxy": "http://dev:s3cret@10.20.30.40:3128", "httpsProxy": "http://dev:s3cret@10.20.30.40:3128", "noProxy": "localhost,127.0.0.0/8,.corp.local" } } }
    这里键名用 camelCase 风格:httpProxy、httpsProxy、noProxy。这是与 daemon.json 的区别,不能混淆。
  3. 保存文件。无需重启,客户端在每次命令时读取它。

现在 docker run 和 docker build 时,容器会自动获得 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY 变量(两种大小写都有)。因此 Dockerfile 中的 apt-get 和 pip 也无需手动 ARG 和 ENV 就能走代理。

Windows 和 macOS 上的 Docker Desktop

通过托盘图标打开设置,Resources 部分,Proxies 子节。切换到 Manual proxy configuration,在 Web Server (HTTP) 和 Secure Web Server (HTTPS) 字段中填入地址,排除列表填入 Bypass proxy settings for these hosts and domains。点击 Apply and restart。Windows 上客户端 config.json 位于 C:\Users\用户名\.docker\config.json,配置方式同上。

建议:docker info 命令输出 HTTP Proxy、HTTPS Proxy 和 No Proxy 部分。这是不启动下载就能知道守护进程是否看到你设置的最快方法。

验证:执行 docker pull hello-world。镜像只有几 KB,几秒即可下载,最后出现 Status: Downloaded newer image。然后检查客户端部分:docker run --rm alpine env | grep -i proxy。输出中应有带你地址的 HTTP_PROXY 和 HTTPS_PROXY 行。

可能的问题

  • 修改 daemon.json 后 Docker 不启动:语法错误。查看 sudo journalctl -u docker -n 30,会指出出错的行。从备份恢复。
  • docker info 显示代理但 docker pull 挂起并超时:修改后守护进程未重启,或代理不允许到 registry-1.docker.io 的 CONNECT。通过 curl 检查基准字符串。
  • 构建中 apt-get update 失败而 docker pull 正常:未配置客户端 config.json,或构建通过读取其他文件的远程 builder 进行。
  • 容器获得代理但无法访问相邻容器:将内部服务名和 Docker 子网加入 noProxy。

第 6 步:通过 git config 配置 git

本阶段目标:git clone、fetch、pull 和 push 通过 HTTPS 走代理,同时内部服务器可保持直连,特定托管可指定单独代理。

git 配置的存储位置

三个层级:系统级(/etc/gitconfig)、用户全局级(~/.gitconfig,Windows 中为 C:\Users\用户名\.gitconfig)和仓库内本地级(.git/config)。代理通常全局设置,针对性排除也是全局但绑定到 URL。

分步配置

  1. 用一条命令为所有 HTTPS 和 HTTP 连接设置代理:
    git config --global http.proxy http://dev:s3cret@10.20.30.40:3128
    与 npm 不同,git 没有单独用于 HTTPS 协议的 https.proxy:http.proxy 键对两者都适用。旧教程中的 https.proxy 设置不是 git 的标准键,会被忽略。
  2. 如果内部服务器不需要代理,为其 URL 设置空值:
    git config --global http.https://git.corp.local.proxy ""
    空字符串表示直连。http. 和 .proxy 之间的部分是规则适用的 URL 前缀。
  3. 如果特定托管需要另一个代理(例如指定的移动代理),同样通过 URL 绑定指定:
    git config --global http.https://github.com.proxy http://dev:s3cret@10.20.30.41:3128
  4. 如果代理替换证书,添加根证书:
    git config --global http.sslCAInfo /etc/ssl/certs/corp-root.pem
  5. 检查最终文件:
    git config --global --list | grep -i proxy
    你会看到 http.proxy=... 和值为空的 http.https://git.corp.local.proxy= 行。

执行这些命令后 ~/.gitconfig 文件如下所示:

[http] proxy = http://dev:s3cret@10.20.30.40:3128 sslCAInfo = /etc/ssl/certs/corp-root.pem [http "https://git.corp.local"] proxy = [http "https://github.com"] proxy = http://dev:s3cret@10.20.30.41:3128

这种粒度通过环境变量无法实现:no_proxy 只能排除主机,不能为不同服务器指定不同代理。

SSH 地址怎么办

http.proxy 设置不影响 git@github.com:user/repo.git 形式的地址,因为那是 SSH 协议而非 HTTP。如果你的代理允许通过 CONNECT 隧道到 22 端口,可以在 ~/.ssh/config 文件中用 ProxyCommand 指令配合 nc 或 corkscrew 工具配置 SSH 客户端。但许多企业代理禁止此类连接。最简单可预测的方法是把远程地址切换为 HTTPS:git remote set-url origin https://github.com/user/repo.git 并使用访问令牌代替密码。

建议:为避免在 ~/.gitconfig 中以明文存储代理密码,可将其放入权限为 600 的单独文件并通过 include 指令引入。创建含 [http] 节的 ~/.gitconfig-proxy,在主文件中添加 [include] path = ~/.gitconfig-proxy。这样主配置就可以放心给同事看。

验证:执行 git ls-remote https://github.com/git/git.git HEAD。几秒后返回带提交哈希和 HEAD 字样的行。该命令不创建文件也不克隆任何内容,是测试网络部分的理想方式。然后验证排除:即使代理不可用,对内网服务器的 git ls-remote 也应正常。

可能的问题

  • Failed to connect to proxy 或 Could not resolve proxy:地址拼写错误。
  • Received HTTP code 407 from proxy after CONNECT:认证错误,检查密码编码。
  • SSL certificate problem: unable to get local issuer certificate:需要 http.sslCAInfo。不要长期使用 http.sslVerify false。
  • URL 规则不生效:前缀必须与 remote 地址的开头匹配。如果 remote 写为 https://www.github.com,则 https://github.com 的规则不会生效。

验证结果:汇总检查清单

配置完五个工具后,运行最终检查。它特意设计为排除环境变量影响,确认起作用的正是配置文件。

  1. 打开新终端并取消已设置的变量:unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY no_proxy NO_PROXY。PowerShell 中:Remove-Item Env:HTTP_PROXY 及其他类似操作。
  2. 检查 npm:npm view express version。预期返回版本号。
  3. 检查 pip:pip download six --no-deps -d /tmp/t。预期下载 whl 文件。
  4. 检查 apt:sudo apt update。预期 Hit 或 Get 行,无 Err。
  5. 检查 Docker:docker pull hello-world 和 docker run --rm alpine env | grep -i proxy。预期下载镜像及容器中的变量。
  6. 检查 git:git ls-remote https://github.com/git/git.git HEAD。预期返回提交哈希。

成功执行的标志

  • 全部六条命令在控制台无环境变量时正常工作。
  • .npmrc、pip.conf、80proxy、daemon.json、config.json 和 .gitconfig 文件中写入的是同一个基准代理字符串。
  • 含密码的文件(80proxy、daemon.json、.npmrc、pip.conf、.gitconfig)权限为 600 或仅 root 可访问。
  • 内部主机的排除生效:即使代理关闭也能访问它们。
  • 原始文件的备份就在旁边,你知道如何恢复。

验证:如果有一项不满足,回到对应工具的部分,将你的文件与指南示例逐字符比对。十次中有九次原因是拼写错误或密码中未编码的字符。

常见错误及解决方案

错误 1:处处出现 407 Proxy Authentication Required

原因:密码包含未编码的特殊字符(@、:、#、%),工具错误解析了地址。

解决:用百分号编码替换字符(@ 变 %40,: 变 %3A,# 变 %23,% 变 %25),写入配置前通过 curl -x 验证新字符串。

错误 2:终端中可用,通过 sudo 不可用

原因:sudo 清空环境,而你还未创建配置文件。apt 的经典问题。

解决:如第 4 步创建 /etc/apt/apt.conf.d/80proxy。对于其他工具在 root 下运行,记住 root 读取自己的主目录 /root 而非你的:如果 root 需要 npm 或 pip,配置应放在 /root/.npmrc 或 /root/.config/pip/pip.conf。

错误 3:修改 daemon.json 后 Docker 不启动

原因:无效 JSON:最后一个元素后多余的逗号、缺失的括号、单引号代替双引号。

解决:执行 sudo journalctl -u docker -n 30,找到错误行,修复文件并在下次重启前通过 python3 -m json.tool 检查。极端情况下恢复 daemon.json.bak。

错误 4:docker pull 正常但 Dockerfile 中 apt-get 失败

原因:配置了守护进程但未配置客户端。容器内进程不继承守护进程设置。

解决:如第 5 步部分 C 创建含 proxies.default 块的 ~/.docker/config.json。之后 docker build 会自动将变量传入 RUN 阶段。

错误 5:所有工具都报 SSL 证书错误

原因:代理执行流量检查并替换为自己的系统不信任的证书。

解决:从管理员处获取 PEM 格式的代理根证书并配置:npm 用 cafile,pip 用 cert,git 用 http.sslCAInfo。对于 apt 和 Docker,将证书加入系统存储即可:复制到 /usr/local/share/ca-certificates/ 并执行 sudo update-ca-certificates,然后重启 Docker。不要用 strict-ssl、trusted-host 和 sslVerify 标志禁用证书检查。

错误 6:pip 忽略 pip.conf

原因:机器上有多个 Python 版本,你为其中一个修改配置却运行另一个。或文件位于该版本不读取的过时位置。

解决:用你安装包时的同一命令运行 python3 -m pip config debug。输出会显示找到哪些文件。将设置移到找到的用户路径中。

错误 7:git 连内网服务器也走代理

原因:排除规则设置用于与 remote 地址不匹配的 URL。或设置在另一个仓库的本地 .git/config 中。

解决:用 git remote -v 查看准确地址,复制开头直到主机名,通过 --global 设置 http.准确URL.proxy 为空值。

错误 8:一切正常但更换代理密码后失效

原因:密码嵌入在五个不同文件中,未全部更新。

解决:使用 grep -rl '旧密码' ~/.npmrc ~/.config/pip ~/.gitconfig ~/.docker 和 sudo grep -rl 针对 /etc/apt/apt.conf.d 和 /etc/docker 查找所有出现位置,更新每一处。然后运行汇总检查清单。

其他功能

本地代理聚合器作为统一入口

如果代理凭据频繁变更或地址池轮换,可在本机搭建轻量本地代理(例如 127.0.0.1:3128),它自己知道去哪里、用什么凭据。这样五份配置中都写入一个无密码地址,凭据变更只在一处修改。这也能解决对 URL 中认证支持不佳的工具问题。

包的镜像和缓存代理

代理不必是通用的。apt 有缓存代理,本地存储 deb 文件并供整个办公室使用。npm 和 pip 方面企业会搭建私有仓库,代理公共仓库并缓存。这种情况下不用 proxy 键,而是在 .npmrc 中用 registry,在 pip.conf 中用 index-url,对外部世界的代理在这个仓库上配置。Docker 类似角色由 daemon.json 中的 registry-mirrors 键承担。

不同项目的独立设置

package.json 旁边的项目级 .npmrc、venv 内的 pip.conf 和本地 .git/config 可以让一个项目走代理而另一个直连。只是不要把含密码的文件提交到仓库:加入 .gitignore 或使用 ${PROXY_URL} 形式的变量替换,npm 在读取 .npmrc 时能从环境展开。

自动化部署

五份配置都是简单的文本文件。便于用脚本或配置管理系统部署:脚本以一个参数接收基准字符串并生成所需格式的文件。部署后用汇总检查清单中的命令验证:它们无需交互,适合自动化测试。

密码存储安全

最低要求——每个含密码的文件权限 600。更好——将机密导出到单独的可引入文件(git 的 include,apt.conf.d 中仅含认证行的单独文件)。最好——使用无密码认证但按 IP 限制的代理,或上述本地聚合器。永远不要将含密码的配置完整发送到聊天和工单中。

FAQ:配置常见问题

现在需要从 .bashrc 中删除 http_proxy 变量吗

不一定。工具配置优先于变量,不会冲突。但如果你希望只有包管理器走代理,浏览器和其他程序直连,最好删除变量:它们影响所有程序。

为什么 npm 的 https-proxy 写的是 http:// 地址而非 https://

因为这是代理服务器本身的地址,而非目标资源的协议。大多数代理以普通 HTTP 接受连接并在内部隧道传输 HTTPS。如果你的代理确实接受 TLS 连接,那就写 https://,但这很少见。

可以使用 SOCKS5 代理吗

npm——不行,它只支持 HTTP 代理。pip——可以,需安装 pysocks 包并使用 socks5://host:port 形式的地址。git——可以,格式 socks5h://host:port,字母 h 表示在代理端解析域名。apt——只能通过额外传输,标准不支持。Docker——不行。实践中从提供商获取 HTTP 端口更简单。

如何快速在所有工具中禁用代理

npm:npm config delete proxy 和 npm config delete https-proxy。pip:pip config unset global.proxy。git:git config --global --unset http.proxy。apt:删除或重命名 /etc/apt/apt.conf.d/80proxy。Docker:从 daemon.json 和 config.json 中删除 proxies 块,重启服务。或者直接从备份恢复 .bak 文件。

Windows 中配置存放在哪里

npm:C:\Users\用户名\.npmrc。pip:C:\Users\用户名\AppData\Roaming\pip\pip.ini。git:C:\Users\用户名\.gitconfig。Docker:客户端用 C:\Users\用户名\.docker\config.json,守护进程用 Docker Desktop 设置。Windows 中不使用 apt,除 WSL 外,WSL 中使用子系统内的 Linux 路径。

在 WSL 中有效吗

是的,WSL 是普通 Linux,所有配置按 Linux 路径位于发行版内。注意,与 WSL 集成的 Docker Desktop 使用 Windows 端守护进程,因此守护进程设置在 Docker Desktop 中进行,而客户端 config.json 在 WSL 的主目录中配置。

如何知道哪个工具读了哪个文件

npm config list --json、pip config debug、apt-config dump、docker info、git config --show-origin --list。每个命令不仅显示值还显示来源。这是调试时应首先运行的。

为什么 Docker Compose 看不到代理

Compose 是客户端,它使用同一守护进程和同一个 ~/.docker/config.json。如果 docker pull 正常而 docker compose pull 不正常,检查你是否以同一用户运行 compose,以及 compose 文件中是否重定义了覆盖代理的容器环境变量。

可以为 npm 和 pip 设置不同代理吗

可以,这正是自有配置的优势。每个文件独立。例如 npm 走一个代理而 pip 走另一个,不同 IP 不同地理定位,如果任务需要的话。

结语

让我们总结一下。你通过 curl 验证了代理并获得了含正确编码密码的基准连接字符串。然后将其写入五处:npm 的 ~/.npmrc、pip 的 pip.conf、apt 的 /etc/apt/apt.conf.d/80proxy、Docker 的 daemon.json 和 ~/.docker/config.json 以及 git 的 ~/.gitconfig。为每个工具在支持的地方设置了内部主机排除,并确认在完全清空的环境下一切正常工作。这正是自有配置与环境变量的区别:它们不依赖于谁、从何处、通过哪个服务运行命令。

接下来做什么。将五份基准文件保存到个人文件夹并编写简短脚本部署到新机器。检查含密码文件的权限。如果有同事遇到同样问题,与他们分享汇总检查清单:它能节省数小时调试时间。

如何进阶。下一个层次是缓存代理和包私有仓库、作为统一入口的本地代理聚合器以及在流水线中自动验证网络设置。如果你需要为终端会话或 CI 任务而非工具配置代理,有专门关于环境变量的指南。现在你清楚知道它的能力边界在哪里,配置文件的能力从哪里开始。