GitHub 克隆慢、Docker 镜像拉取失败、npm 安装依赖超时，表面上都像是“网络不通”，实际可能分别卡在代理未接管、域名分流错误、镜像站不可用、DNS 解析异常或 CI 环境变量没有传入。解决这类问题，与其反复切换线路，不如先明确具体命令访问的目标，再逐层检查代理、客户端配置和构建环境。
本文覆盖本地开发、容器构建、CI 与 API 请求。配置示例中的代理地址仅用于演示，请替换为本机代理客户端实际监听的地址和端口；如果你的客户端使用其他协议或端口，以客户端设置为准。代理只影响遵循相应配置的程序，不意味着设备上的所有连接都会自动经过代理。
先确认故障在哪一层
排查时先记下失败命令、报错原文、运行环境和目标域名。浏览器能打开 GitHub，不代表 Git、Docker daemon 或 CI runner 使用了相同的网络路径；终端里设置了代理，也不代表后台运行的 Docker 服务能够读取当前 shell 的变量。
可以先把问题分成几类：Git 克隆或拉取失败，检查 Git 使用的 HTTPS 或 SSH 连接；镜像拉取失败，检查 Docker daemon 与镜像仓库的连通性；npm 超时，检查当前 registry 和 Node.js 进程的代理设置；只有 API 请求失败，则检查具体程序是否读取代理环境变量。错误提示也有区分价值：解析失败偏向 DNS，连接超时偏向路由或代理，证书错误则应核实系统时间、证书链与 TLS 检查配置。
- ✅ 先在同一终端直接检查命令行工具，不以浏览器访问结果代替测试。
- ✅ 一次只改变一个因素，例如先验证代理，再检查规则或 DNS。
- ✅ 确认本地代理客户端处于运行状态，并核对监听地址、端口和接管模式。
- ❌ 不要把“连接超时”一律归因于出口地区，也不要同时更换代理、镜像和 DNS。
如果你使用 VPN 或代理客户端，应确认开发工具所在的网络请求确实按预期分流。像 VPNText 这类网络服务页面可以帮助了解客户端与线路信息，但具体应用是否走代理，仍要以本机规则、连接记录和命令行测试为准。
本地开发：分别配置 Git、npm 与 API
对 HTTP 或 HTTPS 代理，本地测试可以先在当前终端设置临时环境变量。下面以常见的本机 HTTP 代理端口为例；关闭终端后，临时变量通常不再生效。
export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
export NO_PROXY="localhost,127.0.0.1,::1"Windows PowerShell 可使用当前会话变量，例如 $env:HTTPS_PROXY="http://127.0.0.1:7890"。不同程序对环境变量大小写的处理并不完全一致；遇到变量看似已设置但请求仍直连的情况，应查看该工具的文档，并检查进程启动方式。桌面应用从菜单启动时，可能不会继承你在终端里设置的变量。
Git 使用 HTTPS 克隆时，可以依赖环境变量，也可以单独为 Git 设置代理。以下是可选的全局配置，配置前先确认这是你希望长期使用的代理：
git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890
git config --global --get http.proxy如果只想对某个仓库生效，在该仓库目录内省略 --global，使用仓库级配置。恢复时可执行 git config --global --unset http.proxy 和 git config --global --unset https.proxy。HTTPS 代理配置不会自动解决 SSH 连接问题；如果远程地址以 git@ 开头，排查方向应转到 SSH 的网络路径和密钥配置，不要误以为调整 HTTP 代理一定有效。
npm 可通过配置 registry 选择依赖包源。优先使用项目或组织认可、可验证且长期维护的 registry；需要使用 npm 官方源时，可设置为 https://registry.npmjs.org/。项目依赖安装尽量使用锁文件和 npm ci，让本地与 CI 按锁定版本安装。不要为了绕过证书报错而关闭 TLS 校验，也不要把来历不明的镜像地址写进项目配置。
npm config get registry
npm config set registry https://registry.npmjs.org/
npm ci如使用环境代理，检查启动 Node.js 的终端是否拥有对应变量；某些依赖或工具链还有自己的代理选项。代理设置能够帮助请求经过指定路径，但不能替代对 registry、锁文件、权限和包完整性的检查。API 客户端也类似：命令行工具可能读取 HTTP_PROXY 和 HTTPS_PROXY，自定义程序则可能需要在 HTTP 客户端中显式设置代理。
动手配置：检查 Docker 与 CI 的网络路径
本节按“本地 Docker、构建时依赖、CI runner”顺序操作。每次修改后先重试原命令，并保留错误信息；Docker CLI 能连接 daemon，不代表 daemon 一定能访问镜像仓库。
- 确认失败阶段。区分
docker pull拉取基础镜像失败、构建过程中访问包仓库失败，还是容器运行后 API 请求失败。它们分别涉及 daemon、构建步骤和容器内应用。 - 检查 Docker Desktop。桌面版通常有自己的代理设置入口，具体位置与版本有关。确认代理对 Docker daemon 和构建过程生效后，再用原镜像名称测试。不要仅在终端设置环境变量后，就认定后台 daemon 已继承它。
- 检查 Linux daemon。如果由 systemd 管理 Docker，可按当前发行版的 systemd 配置方式为 daemon 设置代理环境变量，再重新加载配置并重启服务。修改前备份已有配置，并核实服务状态；不要把 shell 的代理配置误当成 system 服务配置。
- 检查镜像来源。确认镜像名、registry 域名、账号权限和标签都正确。镜像加速器或 registry mirror 只有在来源可信、配置符合组织政策且当前可用时才考虑；不要把未经核验的第三方镜像站用于含敏感代码或生产制品的工作流。
- 检查构建网络。构建步骤需要访问 npm、操作系统包仓库或 API 时，确认构建环境能得到所需代理配置。Docker 支持为构建传入代理相关参数；采用时应遵循 Docker 文档和组织的构建规范，避免把代理凭据写入 Dockerfile、镜像层或公开日志。
CI 中应把代理地址、令牌和私有 registry 凭据放在平台提供的受保护变量或 secret 管理功能里，并按任务需要限制可见范围。对于不需要代理的内部服务，可以设置适当的 NO_PROXY；但要准确列出主机名、域名或网段，避免过宽规则让本应代理的请求意外直连。不同 CI 平台的变量注入语法各不相同，不能把一个平台的 YAML 片段直接复制到另一平台。
Docker 构建时，优先采用构建平台提供的 secret 挂载机制处理私有包凭据，不要使用会把密钥固化到镜像的普通构建参数。完成构建后，检查镜像层、构建日志和缓存中是否包含令牌或私有配置。若凭据已经写入公开提交或日志，应立即按对应平台流程撤销并轮换。
代理分流与镜像源：按域名和用途选择
开发工具访问的目标不止一个：Git 仓库、容器 registry、npm registry、系统包仓库和业务 API 可能使用不同域名，甚至由不同组织维护。规则模式下应确认需要的域名是否命中预期规则；如果一个请求依赖多个域名，还要留意重定向、对象存储和鉴权服务。不要只添加一个主站域名，就假设所有下载都已纳入同一条路径。
全局代理可以作为短时对照，帮助判断是否存在分流遗漏，但不宜未经评估就作为长期方案。长期使用全局代理可能改变内部仓库、局域网服务或开发环境的访问路径。排查完成后，应恢复适合日常工作的规则，并用客户端连接记录或目标程序自身的诊断信息确认结果。客户端导入、规则更新与不同系统的使用方式，可参考新手指引；遇到持续性连接问题，可再查看故障排查说明。
镜像源选择也需要按用途区分。公开依赖可以考虑项目维护方认可的源；企业私有包应使用组织指定的 registry 和访问凭据；容器镜像则应确认镜像签名、标签来源及更新策略。更换源可能改变包的可用版本、缓存命中情况或元数据表现，因此不要在问题未定位时同时更换多个 registry。
| 现象 | 优先检查 | 容易忽略的差异 |
|---|---|---|
| Git HTTPS 克隆失败 | Git 代理配置、远程地址、目标域名解析 | SSH 与 HTTPS 使用的连接方式不同 |
| Docker 拉取失败 | daemon 代理、registry 地址、镜像权限 | 终端变量不一定传给后台服务 |
| npm 依赖安装超时 | registry、锁文件、Node.js 进程代理 | 包管理器和单个依赖脚本可能访问不同域名 |
| CI 中 API 请求失败 | runner 网络、受保护变量、NO_PROXY | 本地成功不代表 runner 拥有相同环境 |
常见故障排查与凭据保护
连接超时：先确认代理进程正常，再确认目标应用是否读取代理设置；然后单独测试域名解析与网络连接。若 Git、npm 和 Docker 同时失败，优先检查共享的本地网络或代理入口；若只有一个工具失败，则重点核对该工具自己的配置。
证书错误：检查系统时间、证书链和企业网络中的 TLS 检查策略。不要通过设置 strict-ssl=false 或关闭证书验证来“修复”问题，这会削弱对连接身份的校验。遇到公司内部证书要求，应向管理员获取正确的信任配置。
能访问首页但下载失败：下载资源、API 和登录服务可能属于不同域名。查看程序日志和客户端连接记录，按实际失败域名检查规则，不要直接添加过宽的通配规则。若使用代理分流，先确认该域名的命中策略，再做单项对照。
CI 有时成功、有时失败：核对任务实际运行的 runner、容器网络、依赖缓存和 secret 是否按预期注入。缓存可以减少重复下载，但缓存失效或依赖更新时仍需要访问源站，因此不能把缓存当作网络配置的替代品。保留足以复现问题的日志，同时删除令牌、订阅链接、私有仓库地址等敏感字段。
Git 凭据、npm token、容器 registry 密码、SSH 私钥和代理认证信息都应按密钥管理。不要将它们提交到仓库、写进 Dockerfile、放在可公开读取的日志里，也不要把包含凭据的完整错误截图上传到公共讨论区。若怀疑泄露，尽快撤销或轮换凭据，并检查是否还有自动化任务继续使用旧值。
- ✅ 用受保护的 secret 注入 CI 凭据，并限制任务和人员的访问范围。
- ✅ 在提交前检查配置文件、日志和构建产物是否意外包含令牌。
- ✅ 先做最小范围的代理或源配置变更，并记录如何恢复。
- ❌ 不要关闭 TLS 校验、盲目使用陌生镜像，或把私有凭据写进构建镜像。