开发者 VPN 完整方⁠案：GitHub、Docker 与 npm 加⁠速配置

先理解开发工具的代理路径

桌面 VPN 客户端常见的接管方式包括系统代理、规则分流和 TUN 模式。系统代理通常只影响主动读取操作系统代理设置的程序；规则分流决定已被客户端接管的连接应该直连还是经代理转发；TUN 模式则通过虚拟网络接口接管更多 IP 流量。三者解决的问题不同，不能看到客户端显示“全局”就认为 Git、Docker 和 CI 中的所有请求都会自动经过同一条线路。

Git 命令一般可以读取自身配置中的 HTTP 或 HTTPS 代理，也可能继承当前 shell 的环境变量。npm 有自己的配置文件和命令行参数，Docker CLI 与 Docker daemon 还可能分属两个不同的网络进程。桌面端客户端即使已经能够代理浏览器，也不代表后台 Docker 服务或远程构建器使用了相同出口。因此，排查时应先画出请求发起者：是当前终端、桌面应用、Docker daemon，还是远程 CI runner。

订阅通常提供的是节点信息或客户端可导入的配置，而 Git、npm 和 Docker 更常需要标准的 HTTP、HTTPS 或 SOCKS5 代理参数。Shadowsocks、VMess、Trojan、Hysteria2 和 WireGuard 属于不同的接入协议或隧道方案，不能直接当作 Git 的代理地址填写。正确做法是让兼容客户端负责建立连接，再使用客户端暴露的本地 HTTP 或 SOCKS 监听，供开发工具调用。

GitHub 拉取与推送：分别配置 Git 和 SSH

GitHub 相关操作通常分为 HTTPS 仓库访问和 SSH 仓库访问。HTTPS 模式会使用 Git 的 HTTP 传输层，适合通过 HTTP 或 HTTPS 代理统一管理；SSH 模式使用独立的 SSH 连接，通常不会自动读取浏览器或系统代理。很多人遇到“网页可以打开，git clone 却超时”，原因正是网页和 Git 使用了不同的代理继承方式。

HTTPS 仓库使用独立的 Git 代理

如果本地客户端提供 HTTP 代理，可以在 Git 的全局配置中写入代理地址；如果提供 SOCKS5 代理，应确认当前 Git 版本与本地网络组件对该协议的支持方式。更稳妥的做法是先对单个仓库或当前命令临时设置，确认路径正确后再决定是否写入全局配置。全局配置会影响所有仓库，也可能让公司内网 Git 服务被错误地送往外部线路。

git config --global http.proxy http://127.0.0.1:代理端口
git config --global https.proxy http://127.0.0.1:代理端口
git config --global --get-regexp 'http.*proxy'

上面的地址只是本机代理监听示例，实际端口应以客户端设置为准。若只希望某个项目使用代理，可以在项目目录中去掉 --global，这样配置会写入该仓库的本地设置。测试完成后，使用 git config --unset 或删除对应项目配置，避免把旧端口留给未来的网络环境。

SSH 连接需要单独处理

SSH 仓库地址常见形式是以 git@ 开头的地址。系统代理通常不会自动转换 SSH 流量，因此需要使用客户端支持的 SSH 代理方式，或者改用 HTTPS 仓库地址。部分环境会通过 SSH 配置文件指定代理命令，但这依赖本机是否安装对应的转换工具，也容易与公司安全软件、密钥代理和多账户配置发生冲突。

无论采用哪种方式，都不要把访问令牌、私钥或带认证信息的完整地址直接写进脚本、提交记录或公开日志。CI 中应使用平台提供的密钥变量，并限制令牌权限和作用范围。对于只读构建任务，尽量使用只读凭据；对于推送任务，则应单独管理写入权限，并在任务结束后检查日志是否打印了认证参数。

• ✅ 先用 git ls-remote 检查仓库访问，再进行完整克隆
• ✅ 区分 HTTPS 代理配置与 SSH 连接配置
• ✅ 为公司内网域名保留直连或内部代理规则
• ❌ 不要把访问令牌写入远程地址、Shell 历史或项目文件
• ❌ 不要同时启用多个会修改 Git 代理的脚本

Docker 镜像下载：CLI、daemon 与构建阶段要分开

Docker 的难点在于命令行客户端和 Docker daemon 往往不是同一个进程。你在终端执行 docker pull，实际下载镜像层的可能是后台 daemon；在 Docker Desktop、Linux 服务或远程 Docker 主机中，这两个组件甚至运行在不同的虚拟环境或不同机器上。只给当前终端设置代理，通常不能解决 daemon 无法访问镜像仓库的问题。

先判断 Docker 服务在哪里运行

本机 Docker Desktop 需要检查其引擎或后台服务的网络设置；Linux 上的 Docker daemon 通常需要在服务配置中设置代理，然后重新加载服务配置；远程 Docker 主机则必须在远程主机上配置，不能只改开发电脑。配置完成后，应先查看 daemon 的状态和日志，再执行拉取操作，避免把“配置未生效”误判为“镜像站不可用”。

Dockerfile 中的 RUN 命令又是另一条路径。即使基础镜像能够拉取，构建阶段执行的系统包安装、npm 安装或脚本下载仍可能无法联网。可以在构建环境中临时传入代理参数，但不应把带认证信息的代理地址写入镜像层。更安全的方式是使用构建器提供的 secret 或临时构建参数，并在构建完成后确认最终镜像中没有残留代理配置。

docker pull 示例镜像:标签
docker build --progress=plain -t 本地镜像名 .
docker info
docker system info

镜像加速与代理不是一回事

镜像仓库镜像、企业内部缓存和 VPN 代理解决的是不同问题。镜像缓存可以减少重复下载并降低外部仓库依赖，但它需要仓库内容同步、权限管理和版本策略；代理则改变连接路径，不能保证目标仓库本身一定可用。生产环境中应优先使用组织认可的镜像仓库或缓存服务，不要随意把来源不明的镜像地址写入全局 Docker 配置。

如果拉取在某一层反复失败，应观察是域名解析失败、TLS 握手失败、连接被重置，还是下载过程中断。不同错误对应的处理方法不同：DNS 异常要检查解析路径，TLS 错误要检查系统时间和证书链，下载中断则要检查线路连续性、磁盘空间和 daemon 日志。单纯切换成全局模式，可能只会掩盖规则遗漏。

npm 依赖安装：代理、镜像与证书要分别确认

npm 安装依赖时可能访问包注册表、元数据接口、压缩包下载地址和项目脚本依赖的外部服务。页面能打开不代表这些请求全部成功，因为不同包的 tarball 地址、作用域包和生命周期脚本可能走不同域名。安装过程中长时间停在解析、下载或校验阶段，需要结合 npm 日志判断卡住的具体环节。

优先检查 npm 自身配置

npm 可能读取用户配置文件、项目配置文件和环境变量。多份配置叠加时，旧代理地址、错误的注册表地址或不匹配的证书设置都可能造成异常。建议先查看当前生效配置，再决定是临时参数、项目配置还是用户级配置。团队项目最好通过文档约定注册表和代理策略，不要把个人电脑的本地代理地址提交到仓库。

npm config get registry
npm config get proxy
npm config get https-proxy
npm ping
npm install

如果 npm 需要通过 HTTP 或 HTTPS 代理连接，应使用客户端提供的对应监听地址。SOCKS5 不能在所有 npm 配置位置直接替代 HTTP 代理，必要时应通过兼容层提供标准 HTTP 代理，或者使用 TUN 模式让 npm 直接建立网络连接。不要为了绕过证书错误而长期关闭 TLS 校验；这会削弱依赖完整性和中间人防护。

镜像源适合提速，但要关注一致性

团队可以使用组织维护的 npm 缓存或可信注册表，减少公共网络波动带来的影响。修改注册表后，应确认锁文件、作用域包、私有包权限和构建环境都能访问同一来源。开发机安装成功而 CI 失败，常见原因不是包本身损坏，而是 CI 没有继承用户配置、没有注入私有包令牌，或构建环境无法解析该注册表域名。

npm 生命周期脚本可能在安装过程中执行编译、下载二进制文件或访问额外服务。若基础依赖可以下载，脚本阶段却失败，应查看脚本输出和目标域名，不要只重复执行安装命令。对于来源不明的安装脚本，需要先审查内容和权限；稳定网络不等于可以忽略依赖供应链安全。

CI 环境：让构建网络可重复、可审计

CI 的网络问题经常被误认为是本地配置没有复制完整。实际上，CI runner 可能位于不同地区、使用独立 DNS、没有桌面客户端，也可能运行在容器、虚拟机或受限网络中。将本地的 HTTP_PROXY 和 HTTPS_PROXY 原样复制到 CI，既可能无法访问本机地址，也可能把凭据暴露给任务日志。

更合理的做法是由 CI 平台的密钥管理功能注入代理参数、注册表令牌和 SSH 密钥，并通过受保护变量传给需要的任务。对内部域名设置 NO_PROXY 或平台等效配置，避免内网服务绕远路。不同工具对大写和小写环境变量的读取方式不完全一致，应该在一次最小化测试任务中确认实际生效情况，而不是在完整构建失败后再猜测。

按阶段验证，而不是一次跑完整流水线

1. 先确认 runner 能解析目标域名，并能建立基础 TLS 连接。
2. 再验证 Git 只读拉取，确保仓库凭据和代理路径都正常。
3. 随后验证 npm 元数据和依赖下载，确认私有包权限没有缺失。
4. 最后测试 Docker 基础镜像、构建阶段依赖和推送仓库。

每一步都应保留不包含令牌和完整认证地址的错误摘要。这样可以区分 DNS、代理连接、证书、权限和目标服务故障。构建任务如果偶发失败，应记录 runner 类型、出口策略、缓存命中情况和发生阶段；不要只保存一条“网络超时”的泛化信息。

• ✅ 将代理和注册表凭据放在 CI 密钥管理中
• ✅ 为内网域名设置明确的直连或内部代理规则
• ✅ 使用最小权限令牌，并限制可访问的仓库和注册表
• ✅ 在构建结束后检查镜像层和日志是否残留凭据
• ❌ 不要把本机 127.0.0.1 代理地址直接复制到远程 runner
• ❌ 不要为了临时通过构建而关闭 TLS 校验

一套可执行的排查顺序

当 GitHub、Docker 和 npm 同时出现异常时，建议从最底层开始检查。先确认 VPN 客户端当前使用的接管方式和规则，再确认系统能否解析目标域名；随后检查本地 HTTP 或 SOCKS 监听是否仍在运行，最后分别测试 Git、Docker daemon 和 npm。每次只改变一个变量，并记录客户端、线路、代理类型和错误信息，才能知道哪项改动真正有效。

如果浏览器正常而三个开发工具都失败，优先检查终端是否继承了代理、TUN 是否与其他虚拟网卡冲突，以及本机安全软件是否拦截了命令行进程。如果只有 Docker 失败，重点看 daemon 所在环境；如果只有 npm 失败，重点看注册表、证书和生命周期脚本；如果只有 SSH Git 失败，则不要继续修改 npm 或 Docker 配置。

更换线路后，已经建立的 Git、SSH、镜像下载或 npm 长连接不会自动迁移。遇到切换后任务停顿，应安全结束旧任务，再在新线路下重新执行。开发机器还应避免同时运行多个会改写系统代理、默认路由或虚拟网卡的客户端，否则即使短时间恢复，也很难得到可重复的结果。

如果需要进一步整理客户端导入、系统代理、TUN 模式和分流规则，可以先查看教程，再根据 Git、Docker、npm 的实际请求方逐项配置。稳定的开发网络不是把所有流量永久设为全局，而是让每个工具都知道应该走哪条路径，并且在网络变化后能够安全恢复。