开发时遇到 GitHub 克隆缓慢、Docker 镜像拉取超时，或 npm、pip 依赖下载失败，未必是某一个网站或工具出了问题。不同命令可能使用不同的网络入口：浏览器读取桌面代理设置，终端程序通常读取环境变量，Docker 拉取镜像由守护进程或 Docker Desktop 发起，而容器构建阶段的依赖下载又可能运行在独立的构建环境里。只打开客户端并不代表所有开发工具都会自动走同一条线路。
更稳妥的做法是先确认故障发生在哪一层，再只为需要的工具配置代理或分流规则。本文按 Git、Docker、npm 和 pip 的常见工作流程说明配置位置，并介绍 DNS、路由、CI 环境和凭据保护方面的排查要点。命令中的代理地址均为占位示例，应替换为当前客户端实际提供的本地监听地址；不要照抄不存在的端口或远端服务器地址。
先区分开发工具的网络路径
同一台电脑上，浏览器能打开代码托管网站，不等于 Git 一定能拉取仓库；终端能访问仓库，也不等于 Docker 守护进程能下载镜像。排查时先记录失败的具体命令、错误信息、运行位置和目标域名，再判断请求由哪个组件发出。尤其要区分宿主机命令、Docker 守护进程、构建容器和 CI 执行器，它们可能拥有各自的代理设置、DNS 配置和出口路由。
| 工作环节 | 常见请求发起者 | 优先检查 | 容易忽略的问题 |
|---|---|---|---|
| Git 克隆与拉取 | Git 命令行进程 | 仓库地址使用 HTTPS 还是 SSH、Git 配置、终端代理环境变量 | 浏览器代理设置不会必然自动传给 Git |
| Docker 拉取镜像 | Docker Engine 或 Docker Desktop | 守护进程代理、镜像仓库地址、镜像源配置 | 只给当前终端设置代理，未必能改变守护进程的请求路径 |
| 镜像构建时安装依赖 | BuildKit 或其他构建后端中的构建步骤 | 构建代理参数、容器内包管理器配置、构建网络 | 宿主机可以联网，不代表构建阶段也能联网 |
| npm 与 pip 安装 | 本机进程或容器内进程 | 环境变量、工具级代理设置、包仓库地址 | 本机配置不会自动复制到容器或 CI 运行器 |
先用一个简单的 HTTPS 请求测试目标域名，再运行原始工具命令，有助于缩小范围。若浏览器和通用请求工具都无法连接，优先检查当前网络、客户端连接状态和 DNS；若只有某个命令失败，则检查该命令自己的配置、认证方式及所在运行环境。不要同时更改 DNS、代理、仓库地址和防火墙规则，否则即使问题暂时消失，也很难确认真正原因。
配置 Git、npm 与 pip
如果客户端提供本地 HTTP 代理，可先在当前终端会话设置环境变量，验证目标命令是否恢复。以下示例中的地址只是格式占位符：
# Linux / macOS
export HTTP_PROXY="http://127.0.0.1:本地端口"
export HTTPS_PROXY="http://127.0.0.1:本地端口"
export NO_PROXY="localhost,127.0.0.1,::1"
# Windows PowerShell
$env:HTTP_PROXY = "http://127.0.0.1:本地端口"
$env:HTTPS_PROXY = "http://127.0.0.1:本地端口"
$env:NO_PROXY = "localhost,127.0.0.1,::1"环境变量只对当前终端及其启动的子进程有效；关闭终端后设置通常就不再存在。NO_PROXY 用于让本机服务、内网域名或无需代理的目标直接连接，具体范围应按开发环境调整。企业内网、私有仓库和本地容器服务若被错误地送到外部代理，可能导致连接失败或违反组织策略，因此不要简单地把所有域名都交给代理。
Git 使用 HTTPS 克隆时，可以临时沿用终端代理变量，也可以配置 Git 自己的代理项。仅在确有需要时设置，并注意全局配置会影响此用户的其他仓库：
# 为当前 Git 用户设置代理
git config --global http.proxy "http://127.0.0.1:本地端口"
# 检查设置
git config --global --get http.proxy
# 不再需要时移除
git config --global --unset http.proxy如果问题只发生在某个仓库，可在仓库目录内省略 --global，将设置限制在该仓库。SSH 形式的仓库地址不使用 Git 的 HTTP 代理选项；它走 SSH 连接，能否使用代理取决于 SSH 客户端和网络策略。不要为了绕过连接问题随意改写仓库地址，也不要把访问令牌放进 URL 后提交到配置文件、脚本或日志中。对组织仓库，应使用获准的认证方式和访问权限。
npm 和 pip 通常可以读取终端代理环境变量；也可以在工具支持的配置中指定代理。使用时应检查当前项目、用户级配置和 CI 配置是否互相覆盖。只有在确认需要工具级配置后，再通过对应命令写入；若代理需要用户名或密码，不要把完整凭据直接写进会提交的项目配置文件。对于依赖源，优先使用项目或组织批准的仓库地址，避免将包切换到来源不明的镜像。
# 查看 npm 的代理相关配置
npm config get proxy
npm config get https-proxy
# pip 可通过环境变量读取代理，也可在命令执行时指定
python -m pip install --proxy "http://127.0.0.1:本地端口" 包名若某个包安装失败，不要立即判断是代理问题。核对包名和版本是否存在、Python 或 Node.js 版本是否兼容、证书是否可信，以及错误发生在 DNS 解析、TLS 握手还是文件下载阶段。把完整错误中的令牌、用户名、私有仓库地址和内部主机名遮盖后，再用于团队协作或提交问题记录。
配置 Docker 拉取与构建网络
Docker 的网络问题需要先区分“拉取已有镜像”和“构建镜像时下载依赖”。前者通常由 Docker Engine 或 Docker Desktop 发起，终端里临时设置环境变量未必能影响它。Docker Desktop 用户应在应用提供的代理设置中核对代理状态和例外域名；Linux 上的 Docker Engine 则应按照当前发行版与 Docker 版本，为守护进程配置代理环境，并在修改后按系统服务管理方式重新加载配置和重启服务。重启可能影响正在运行的容器，操作前先确认维护窗口和工作负载状态。
镜像仓库镜像与通用网络代理不是一回事。镜像源只适用于其明确支持的仓库和访问方式，不能假设一个地址能替代所有注册表。配置前核对镜像源的运营方、支持范围、认证要求和安全策略；组织项目应使用管理员批准的仓库。也不要把 Docker Hub 镜像加速配置误认为 GitHub、npm 或 pip 的加速设置，它们解决的是不同请求路径。
镜像已经可以拉取，但 Dockerfile 中的依赖安装仍然超时，问题通常发生在构建阶段。BuildKit 支持通过代理构建参数向构建步骤传递代理设置；应按 Docker 文档与当前构建方式配置，并确认代理地址对构建容器所在网络可达。构建容器中的 127.0.0.1 指向容器自身，不一定是宿主机上的代理客户端。Docker Desktop、Linux 主机和远程构建器之间的网络拓扑不同，不能机械照搬同一地址。
# BuildKit 构建示意：使用实际可达的代理地址
docker build \
--build-arg HTTP_PROXY="http://代理主机:本地端口" \
--build-arg HTTPS_PROXY="http://代理主机:本地端口" \
-t 示例镜像:dev .
# 拉取镜像时先核对仓库名与标签
docker pull 仓库地址/镜像名:标签构建代理参数可能包含认证信息，不应输出到构建日志，也不要在 Dockerfile 中写入长期有效的代理密码或访问令牌。CI 中应通过平台提供的受保护变量或凭据机制注入，并限制可读取该凭据的工作流范围。构建完成后还应检查镜像层和日志，确认没有把认证信息复制进最终镜像。
- ✅ 拉取镜像失败时，先确认 Docker 守护进程或 Docker Desktop 的代理配置。
- ✅ 构建步骤失败时，单独检查构建网络与包管理器配置。
- ✅ 使用可信、获准的注册表和依赖源，并核验镜像名称与标签。
- ❌ 不要把宿主机的回环地址默认当成容器或远程构建器可访问的代理地址。
- ❌ 不要把令牌、代理密码或私有仓库凭据写入 Dockerfile 和公开日志。
按顺序完成一次配置验证
下面的流程适合在开发电脑上逐项定位，不要求一次性修改所有工具。每完成一项，就用对应的原始命令验证，并记录结果。若设备由公司或学校管理，应先确认代理、证书和软件源的使用规范。
- 记录失败现场：保存失败命令、错误类型、目标域名，以及请求发生在宿主机、容器还是 CI。分享日志前遮盖账号、令牌和内部地址。
- 确认客户端状态：检查所用网络客户端是否已连接，确认当前规则是否覆盖目标域名。若使用 Clash Verge、sing-box 或其他兼容客户端，核实系统代理、规则模式和终端流量处理方式；客户端名称本身不能证明命令行请求已被接管。
- 测试终端请求：在当前终端检查代理环境变量，再用 HTTPS 请求测试目标域名。若直接请求可以、Git 失败，继续检查 Git 的 HTTPS 或 SSH 认证路径；不要同时更改不相关的工具配置。
- 单独验证 Git：使用项目原有的仓库地址执行克隆或拉取。区分 DNS 错误、连接超时、TLS 错误与权限拒绝：前几类多指向网络或证书问题，权限拒绝则应核对账号授权和密钥。
- 验证 Docker 两个阶段：先单独拉取一个项目批准的镜像，再执行镜像构建。如果拉取成功而构建失败，重点检查构建器是否能访问包仓库、代理地址是否在构建环境可达，以及 Dockerfile 中的依赖源是否正确。
- 逐项验证包管理器：分别运行 npm 或 pip 的原始安装命令，检查工具配置、环境变量和包源。一次只改一个变量，成功后再决定是否写入用户级或项目级配置。
- 整理可复现记录：记录操作系统、客户端模式、工具版本、目标服务和处理结果，不记录可复用的凭据。这样能帮助团队成员在不同设备上复现问题，而不必传播个人代理配置。
若连接在更换网络后才失效，可先恢复客户端默认规则并重新测试，避免残留的系统代理或旧环境变量继续影响请求。需要长期设置时，优先采用范围较窄、容易撤销的配置，例如仅对单个终端会话或单个仓库生效；确认稳定后再考虑写入用户级设置。任何全局变更都应留下恢复方法。
排查 DNS、路由与 CI 环境
DNS 负责把域名解析为地址，但解析成功并不代表后续连接一定可用。解析失败时，检查当前网络使用的 DNS、客户端是否接管 DNS 请求，以及目标域名是否被错误地加入直连或代理规则。若解析正常但连接超时，应继续查看路由、出口可达性和防火墙策略。对于企业内网域名，错误地使用公共解析或外部代理，可能造成无法访问或泄露内部查询信息，应遵循组织的 DNS 配置。
分流规则会让不同域名走不同路径。Git 仓库、容器注册表、包仓库和公司内部服务可能不在同一规则类别中；域名还可能由 CDN 或对象存储提供下载，因此只检查主站域名不一定够。遇到间歇性故障时，查看客户端连接记录中的目标域名与实际出口，确认请求是否按预期匹配规则。不要依靠未经验证的固定 IP 代替域名，服务端地址可能变化，也可能导致证书校验和访问策略异常。
路由问题可以按层观察：先确认本机能否解析目标域名，再检查 TCP/TLS 连接是否建立，最后观察具体工具返回的认证或应用层错误。系统自带的 DNS 查询、路由跟踪和连接测试工具可以提供线索，但不同系统的命令和权限要求不同，测试结果也会受到防火墙限制。单次跟踪中断不能直接证明目标服务不可达，需结合实际 Git、Docker 或包管理器命令判断。
CI 环境尤其容易出现“本地正常、流水线失败”。运行器可能是托管主机、组织自建主机或容器化执行器，网络出口与开发电脑不同。应确认代理变量是否在正确的作业步骤中注入、容器任务是否继承变量、NO_PROXY 是否包含内部服务，以及代理凭据是否通过受保护的密钥管理功能提供。不要在仓库中提交个人电脑的代理地址，也不要假设 CI 与本地共享同一 DNS 或路由。
当依赖安装失败时，还要区分网络故障与供应链配置问题。检查 lockfile 是否与包管理器版本兼容，依赖是否来自预期仓库，证书链是否被正确验证；不要通过关闭 TLS 证书校验来“修复”下载错误。临时改用其他软件源之前，先确认来源可信、包内容可验证，并按团队的依赖审查流程操作。
兼顾账号安全与配置维护
代理配置可能携带认证信息，Git、npm、pip、Docker 和 CI 日志也可能包含私有仓库地址或访问令牌。配置时遵循最小暴露原则：凭据只授予必要权限、只在需要的环境中使用，并通过操作系统或 CI 平台提供的安全存储方式管理。不要将令牌粘贴到公开问题、终端截图、提交记录或可被他人读取的构建日志中；发生泄露时应及时撤销并轮换。
同时应区分网络代理凭据与代码托管平台凭据。代理只能改变请求路径，不能替代仓库授权；如果错误信息是权限拒绝，应检查令牌范围、SSH 密钥和仓库权限，而不是不断更换线路。反过来，认证通过也不说明网络路径安全，仍应确保连接使用受信任的 TLS 证书，并避免安装来源不明的根证书。
配置完成后，保留一份不含秘密信息的维护记录：说明代理设置作用范围、如何检查生效状态、如何撤销配置，以及 Docker Desktop、系统服务和 CI 分别由谁维护。软件更新、客户端规则变化、网络切换或 CI 执行器调整后，都可能改变原有路径。遇到问题时从最近变更开始排查，通常比反复重装工具更有效。