开发者遇到 GitHub 克隆慢、Docker Hub 镜像拉取卡住或依赖安装超时，通常不是一个开关就能解决的问题。Git 客户端、Docker 守护进程、容器构建步骤和包管理器可能分别使用不同的网络路径；即使浏览器已经通过代理访问网页，命令行工具也未必自动使用同一代理。排查时先按工作流拆分请求，再逐层配置和验证，避免把问题误归结为单一线路。
本文围绕代码克隆、镜像拉取、依赖下载和 CI 构建说明通用配置思路。具体代理地址、协议和环境变量名称应以你使用的网络服务与客户端文档为准；不要将账号凭据、订阅链接或团队内部地址复制到公开仓库。配置网络时也应遵循 GitHub、Docker Hub、包管理器及所在组织的使用条款。
先拆清楚请求经过哪些组件
同一台开发机上可能同时存在系统代理、终端环境变量、Git 单独代理、Docker Desktop 代理和 Docker Engine 守护进程代理。它们彼此并不总是自动继承。例如，浏览器能够打开 GitHub，不代表终端中的 Git、Docker 后台服务或 CI Runner 已经使用相同出口。先确定具体卡在哪一步，才能把设置放到真正发起请求的组件上。
| 工作环节 | 主要发起请求的组件 | 优先检查 |
|---|---|---|
| 克隆与拉取代码 | Git 命令行及其 HTTP 客户端 | 仓库地址、Git 代理配置、DNS 与 TLS 错误 |
| 拉取基础镜像 | Docker Engine 或 Docker Desktop 后台 | 守护进程的代理设置、Registry 登录状态及镜像名称 |
| 构建时下载依赖 | 构建容器内的包管理器或 BuildKit | 构建步骤是否获得必要代理参数，依赖源是否可访问 |
| CI 自动构建 | CI Runner、容器引擎与构建环境 | Runner 所在网络、密钥注入方式及作业级代理配置 |
记录一条失败命令、完整报错和发生阶段，通常比反复切换节点更有效。超时可能表示连接建立失败，也可能是某个大文件传输中断；认证失败、证书错误和 DNS 解析失败则需要不同处理。可以先用 GitHub 或 Docker Hub 的官方地址进行小范围验证，不要为了“加速”而把仓库地址改成来历不明的镜像站。
- ✅ 浏览器正常但终端失败：分别检查终端环境变量和 Git 配置。
- ✅ Docker 拉取失败：确认代理配置是否作用于 Docker Engine，而不只作用于容器。
- ✅ 镜像能拉取但构建失败：检查构建步骤内部的依赖下载路径。
- ✅ 本地成功但 CI 失败：检查 Runner 的网络环境与密钥配置，不要照搬个人电脑的设置。
- ❌ 不把“能打开网站”当作所有命令行组件都已走代理的证明。
为 Git 配置代理并验证克隆
先确认 Git 使用 HTTPS 还是 SSH。HTTPS 仓库一般会通过 Git 所依赖的 HTTP 客户端建立连接；SSH 则使用 SSH 客户端和相应的网络配置。两种方式的代理设置并不相同。若团队使用 SSH 密钥，不要仅因 HTTPS 代理配置生效就假设 SSH 也会自动经过同一路径。
对于支持 HTTP 代理的本机环境，可以在当前终端临时设置代理变量，再执行一次克隆进行对照。以下地址只是格式示例，请换成你的代理监听地址；若代理需要认证，不要把用户名和密码直接写入命令行历史或脚本。
export HTTP_PROXY="http://127.0.0.1:PORT"
export HTTPS_PROXY="http://127.0.0.1:PORT"
git ls-remote https://github.com/OWNER/REPOSITORY.git
git clone https://github.com/OWNER/REPOSITORY.git如果希望 Git 使用独立配置，可以设置 HTTP 代理并检查当前生效值。代理地址应与客户端实际提供的协议类型一致；SOCKS 代理、HTTPS 代理和普通 HTTP 代理不能只靠替换端口号互相等同。配置完成后，用 git config --show-origin --get http.proxy 查看值来自哪里，排查时也可查看仓库级、用户级与系统级配置是否互相覆盖。
git config --global http.proxy "http://127.0.0.1:PORT"
git config --show-origin --get http.proxy
# 排障结束后，移除这项全局配置
git config --global --unset http.proxy只为单条命令设置代理，适合临时对照测试，也能避免代理配置意外影响公司内网仓库。Git 的代理设置不会替代 GitHub 身份验证；遇到权限错误时，应检查仓库访问权限、SSH Key 或官方支持的凭据管理方式，而不是将访问令牌拼进仓库 URL。使用 Git LFS 的项目还可能通过额外端点传输大文件，普通代码克隆成功并不能证明 LFS 下载链路也正常。
区分 Docker 拉取、构建与容器代理
Docker 使用中最容易混淆的是三个不同环节：Docker Engine 拉取基础镜像、构建工具执行 Dockerfile，以及已启动容器访问外部服务。Docker 客户端配置中的代理选项在某些环境下用于向容器或构建过程提供代理信息，不应直接等同于 Docker Engine 拉取镜像时所需的代理。先看错误发生在 docker pull、构建的某个步骤，还是容器运行之后，再配置相应层级。
使用 Docker Desktop 时，优先在应用设置中检查其网络或代理选项，并按当前版本的官方说明应用更改。Linux 上的 Docker Engine 通常作为后台服务运行，终端里导出的变量不一定会传给守护进程。应根据发行版和 Engine 的管理方式，在服务层设置代理，然后按官方步骤重新加载配置并重启服务。修改前保存现有配置，尤其是团队机器或共享构建机，避免覆盖已有的 Registry、证书或网络设置。
构建阶段若需访问包管理器，应确保构建环境获得了必要配置。BuildKit 支持通过预定义代理构建参数传递代理信息；将代理作为构建参数使用时，不要把凭据写进 Dockerfile、镜像标签或最终镜像层。也不要将整个主机环境不加筛选地传入容器，因为其中可能包含云平台令牌、内部服务地址或其他不相关的敏感变量。
# 示例：由当前终端向构建过程提供代理值
docker build \
--build-arg HTTP_PROXY="$HTTP_PROXY" \
--build-arg HTTPS_PROXY="$HTTPS_PROXY" \
-t my-app:dev .
# 拉取官方镜像时保留官方 Registry 地址
docker pull docker.io/library/alpine:latest镜像拉取遇到超时，先确认镜像名称、Registry 地址和账号权限，再检查 Engine 的代理及 DNS 配置。若提示速率限制或未授权，应根据 Registry 的官方规则登录或调整拉取频率；代理不能绕过访问权限，也不保证消除服务端限制。自建镜像缓存或企业 Registry 适合团队在授权范围内减少重复下载，但应确认镜像来源、签名或摘要校验要求，并维护同步与更新策略。
按一次完整开发流程逐步排查
以下步骤适合在个人开发机上建立可复现的基线。每次只改变一个设置，并记录结果；这样当某一步改善或恶化时，可以判断变化来自 Git、Docker、DNS 还是构建环境。团队共享机器上执行前，先确认你有权限修改系统代理或后台服务设置。
- 检查基础连通性。确认当前网络能够访问代理服务本身，并记录所用客户端、代理类型和监听地址。不要把监听端口当作通用固定值，应以本机实际配置为准。
- 测试 Git 请求。用
git ls-remote查询一个你有权访问的 HTTPS 仓库。如果命令成功，再执行克隆；如果失败，先根据报错区分 DNS、连接超时、TLS 和认证问题。 - 单独测试镜像拉取。使用项目实际依赖的官方镜像执行
docker pull。若 Git 正常而 Docker 失败，检查 Engine 或 Desktop 的代理，而不是继续修改 Git 设置。 - 检查构建步骤。运行一个最小构建，观察失败发生在拉取基础镜像还是 Dockerfile 中的依赖安装。必要时查看 BuildKit 日志，但避免开启会泄露秘密变量的详细输出并将日志公开。
- 恢复日常配置并复测。移除仅用于排查的临时变量或全局设置，确认内网地址、版本控制服务和本地开发工具仍按预期工作，再运行项目原有的构建流程。
依赖管理器也需要逐一核对。npm、pip、Maven、Gradle、apt 等工具可能读取不同的配置文件、环境变量或系统信任库；不要假设它们自动采用 Git 的代理设置。优先使用项目或组织认可的依赖源，并确认 HTTPS 证书校验仍然开启。若只有某个依赖下载失败，可先确认包名、版本、源站和锁文件，再判断是网络问题还是依赖源本身的问题。
需要检查 DNS 时，分别观察目标域名是否解析、代理客户端是否接管 DNS 请求，以及终端和 Docker 环境使用的解析配置是否一致。更改 DNS 并非所有超时问题的通用解法；不熟悉企业网络策略时，不要擅自替换内部 DNS，否则可能影响私有仓库、单点登录或内网服务。
将配置带入 CI，同时保护凭据
CI 作业运行在 Runner 的网络环境中，不会自然继承开发者电脑上的代理。GitHub 托管 Runner、自建 Runner、容器 Runner 和 Kubernetes Runner 的网络边界都可能不同。先确认作业由哪类 Runner 执行、访问外网是否受策略限制，再决定是在 Runner 主机、容器引擎还是单个构建步骤配置代理。网络配置若需组织批准，应先由管理员评估，不要通过未授权隧道绕过团队策略。
代理地址若含认证信息，应存放在 CI 平台的加密密钥或组织级秘密管理功能中，并按作业所需的最小范围注入。避免把凭据写进 workflow 文件、Dockerfile、构建缓存、工件和日志。完成配置后检查失败日志是否会输出代理变量；如果认证信息曾经进入公开日志或仓库，应按凭据泄露流程撤销并轮换，而不是只删除可见文本。
对于团队构建，优先明确依赖源与基础镜像的来源、更新责任和回滚方式。内部缓存可以减少重复传输，但缓存内容也需要访问控制与完整性检查。不要为了构建速度关闭 TLS 校验、忽略证书错误或使用未经验证的镜像替代品；这些做法会把短期网络问题转变为供应链风险。
最终配置应满足三点：能解释每类请求由哪个组件发起；能在本机与 CI 分别复现和定位问题；不会把凭据或团队网络细节泄露到代码库和日志中。若需要客户端安装与订阅导入说明，可查看快速上手；查询可用线路时，可前往线路页面。选择方案前还应核对目标服务条款、所在组织政策及相关法律要求。