GitHub 和 npm 的代理：来自被封锁国家的访问

```html

GitHub 被封锁，延迟 10-30 秒，或者 npm install 在中途卡住——这是来自俄罗斯、伊朗、中国和其他一些国家的开发人员常见的情况。解决方案是存在的，而且比看起来简单：正确配置的代理可以在没有 VPN 和不需要额外麻烦的情况下提供稳定的访问 GitHub 的代码库、包和 API。

为什么 GitHub 和 npm 被封锁或减速

在设置代理之前，了解您所面临的具体问题非常重要。访问 GitHub 和 npm 的问题有三种类型，每种类型都需要不同的解决方案。

国家级完全封锁

一些国家——如中国、伊朗、朝鲜，以及自 2022 年以来不时出现的俄罗斯——在 DNS 或 IP 级别封锁 GitHub。这意味着对 github.com 的请求要么根本无法通过，要么返回连接错误。此时，npm 注册表（registry.npmjs.org）可能正常工作——或者也被封锁。

企业防火墙和网络限制

即使没有国家封锁，企业网络也常常限制对外部代码库的访问。这在银行、政府机构和大型企业中是标准做法：IT 部门会关闭对 443 端口的出站连接或封锁特定域名。在这样的网络中，开发人员无法进行 git clone 或 npm install，除非找到绕过的方法。

由于地理位置导致的慢速

从技术上讲，GitHub 是可访问的，但克隆一个 500MB 的代码库需要 40 分钟，而通过 npm 安装依赖项则需要更长时间。这是路由问题：数据包通过拥挤的节点或长途路线传输。位于美国或欧洲的代理服务器可以缩短路径，并在速度上提供 3-10 倍的提升。

重要的是要理解：

代理解决了这三种问题：绕过封锁，通过允许的端口隧道流量，并通过地理上接近的出口节点提高速度。同时，代理在特定应用程序级别工作——Git、npm、浏览器——而不影响机器上的其他流量。

代理 vs VPN：在处理代码时选择什么

许多开发人员习惯性地选择 VPN。这是可以理解的——VPN 设置简单，并且对整个系统立即生效。但在处理 GitHub 和 npm 时，代理通常更方便。让我们来看看它们之间的区别。

标准	代理	VPN
流量覆盖	仅限特定应用程序（Git、npm）	整个系统的所有流量
CI/CD 中的设置	通过环境变量，简单	需要安装客户端，复杂
在 Docker 中工作	通过 ENV 传递，没有问题	需要特权模式
速度	高（没有加密所有流量）	由于加密而较低
与企业网络的冲突	最小	频繁（被 IT 部门封锁）
在服务器上的使用	通过 env 变量原生支持	需要安装守护进程

结论很简单：如果您的任务是为团队提供对 GitHub 和 npm 的访问，代理只需在配置中设置一次，并且无需干预每台机器的系统设置。这对 CI/CD 管道尤其重要，因为 VPN 在物理上很难设置。

哪种类型的代理适合 GitHub 和 npm

并非所有代理在处理 Git 和 npm 时都表现良好。选择取决于您的任务：绕过封锁、加速下载或在企业网络中工作。

HTTP/HTTPS 代理

最简单的选择。Git 和 npm 原生支持通过标准环境变量配置 HTTP 代理。适用于大多数任务：克隆代码库、安装包、使用 GitHub API。如果您的代理提供商提供 HTTP 地址——从这里开始。

SOCKS5 代理

更灵活的协议，在 TCP 级别工作。支持任何类型的流量，包括与 GitHub 的 SSH 连接（端口 22）。如果您通过 SSH 而不是 HTTPS 使用 Git——SOCKS5 更可取。Git 通过配置中的 socks5:// 参数支持 SOCKS5。

住宅代理

住宅代理使用真实家庭用户的 IP 地址。如果您在一个有严格封锁的国家工作，这一点尤其重要：这些 IP 很少被列入黑名单，看起来像普通用户流量。适用于数据中心 IP 已在提供商级别被封锁的情况。

数据中心代理

数据中心代理是大多数开发人员的最佳选择。它们比住宅代理更快，成本更低，并提供稳定的连接。如果 GitHub 只是慢而不是被封锁——美国或欧洲的数据中心代理在克隆和下载包时将提供最大的速度提升。

代理类型	速度	绕过封锁	最适合
数据中心 HTTP	⭐⭐⭐⭐⭐	中等	加速下载，npm install
数据中心 SOCKS5	⭐⭐⭐⭐⭐	中等	通过 SSH 使用 Git，灵活配置
住宅	⭐⭐⭐	高	严格封锁（伊朗，中国）
移动	⭐⭐⭐	非常高	最大绕过，少数情况

为 Git 设置代理：逐步指南

Git 通过内置配置和环境变量支持代理。我们将展示两种方法——选择适合您工作流程的那种。

方法 1：通过 git config（推荐）

这是一个永久设置，适用于机器上的所有 Git 操作。打开终端并执行：

# 对于 HTTP/HTTPS 代理
git config --global http.proxy http://username:password@proxy-host:port
git config --global https.proxy http://username:password@proxy-host:port

# 对于 SOCKS5 代理
git config --global http.proxy socks5://username:password@proxy-host:port
git config --global https.proxy socks5://username:password@proxy-host:port

# 检查设置是否生效
git config --global --list | grep proxy

将 username:password@proxy-host:port 替换为您的代理信息。如果代理没有身份验证——请删除 username:password@。

方法 2：通过环境变量

适合临时使用或在脚本中使用。Git 会自动获取标准环境变量 HTTP_PROXY 和 HTTPS_PROXY：

# Linux / macOS — 添加到 ~/.bashrc 或 ~/.zshrc
export HTTP_PROXY="http://username:password@proxy-host:port"
export HTTPS_PROXY="http://username:password@proxy-host:port"
export NO_PROXY="localhost,127.0.0.1,::1"

# Windows（PowerShell）
$env:HTTP_PROXY="http://username:password@proxy-host:port"
$env:HTTPS_PROXY="http://username:password@proxy-host:port"

# 在不重启终端的情况下应用（Linux/macOS）
source ~/.bashrc

仅为 GitHub 设置代理

如果您只想通过代理转发对 GitHub 的请求，而不是所有代码库，请使用分区设置：

# 仅对 github.com 使用代理
git config --global http.https://github.com.proxy http://username:password@proxy-host:port

# 检查通过代理克隆
git clone https://github.com/username/repo.git

通过 SOCKS5 使用 Git 进行 SSH

如果您通过 SSH（而不是 HTTPS）与 GitHub 一起工作，设置会稍有不同。您需要编辑文件 ~/.ssh/config：

# ~/.ssh/config

Host github.com
    HostName github.com
    User git
    # 在 Linux/macOS 上使用 nc（netcat）
    ProxyCommand nc -X 5 -x proxy-host:port %h %p
    
    # 或者通过 connect-proxy（需要安装）
    # ProxyCommand connect -S proxy-host:port %h %p
    
    # 在 Windows 上通过 Git Bash
    # ProxyCommand connect -S proxy-host:port %h %p

之后，命令 git clone [email protected]:user/repo.git 和 git push 将自动通过 SOCKS5 代理进行。

如何重置代理设置

# 从全局配置中删除代理
git config --global --unset http.proxy
git config --global --unset https.proxy

为 npm、yarn 和 pnpm 设置代理

每个包管理器都有自己的代理设置方式。我们将介绍 npm、yarn 和 pnpm 三者的具体命令。

npm

npm 通过内置配置设置代理：

# 为 npm 设置代理
npm config set proxy http://username:password@proxy-host:port
npm config set https-proxy http://username:password@proxy-host:port

# 检查设置
npm config get proxy
npm config get https-proxy

# 测试：通过代理安装包
npm install lodash

# 重置代理
npm config delete proxy
npm config delete https-proxy

设置将保存在文件 ~/.npmrc 中。您可以直接编辑它：

# ~/.npmrc
proxy=http://username:password@proxy-host:port
https-proxy=http://username:password@proxy-host:port
strict-ssl=false

参数 strict-ssl=false

如果代理拦截 SSL 流量（例如企业代理），npm 可能会对证书发出警告。参数 strict-ssl=false 将禁用验证。仅在您信任代理的企业网络中使用——在公共网络中这样做是不安全的。

Yarn（v1 Classic）

# Yarn Classic (v1)
yarn config set proxy http://username:password@proxy-host:port
yarn config set https-proxy http://username:password@proxy-host:port

# 检查
yarn config get proxy

# 重置
yarn config delete proxy
yarn config delete https-proxy

Yarn Berry（v2+）

# Yarn Berry 使用环境变量
# 添加到项目根目录的 .yarnrc.yml 中：
httpProxy: "http://username:password@proxy-host:port"
httpsProxy: "http://username:password@proxy-host:port"

# 或通过环境变量
export HTTP_PROXY="http://username:password@proxy-host:port"
export HTTPS_PROXY="http://username:password@proxy-host:port"

pnpm

# pnpm 使用与 npm 相同的 .npmrc
# 如果 npm 已经设置，设置将自动应用

# 或通过 pnpm config 显式设置
pnpm config set proxy http://username:password@proxy-host:port
pnpm config set https-proxy http://username:password@proxy-host:port

替代方案：npm 注册表镜像

如果 npm 注册表速度慢，但 GitHub 可访问——可以切换到镜像。流行的选项有：Taobao（适用于中国）、Verdaccio（自托管）。但镜像常常滞后于包的版本，因此代理更可靠：

# 将注册表切换到镜像（仅用于加速，不用于封锁）
npm config set registry https://registry.npmmirror.com

# 恢复官方注册表
npm config set registry https://registry.npmjs.org

CI/CD 中的代理：GitHub Actions、Docker、Jenkins

在本地机器上设置代理只是部分工作。真正的挑战是确保在隔离网络中运行的 CI/CD 管道能够访问 GitHub 和 npm。让我们讨论三种最常见的场景。

GitHub Actions

在 GitHub Actions 中，代理通过工作流文件中的环境变量进行设置。将秘密添加到存储库的设置中（设置 → 秘密），然后在工作流中使用它们：

# .github/workflows/build.yml
name: Build

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    
    env:
      HTTP_PROXY: ${{ secrets.PROXY_URL }}
      HTTPS_PROXY: ${{ secrets.PROXY_URL }}
      NO_PROXY: "localhost,127.0.0.1"
    
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Configure npm proxy
        run: |
          npm config set proxy ${{ secrets.PROXY_URL }}
          npm config set https-proxy ${{ secrets.PROXY_URL }}
      
      - name: Install dependencies
        run: npm ci

Docker

在 Docker 中，代理在两个层面上都是必需的：在构建镜像时（在 docker build 中）和在容器内部。这是不同的设置：

# 在构建时通过 --build-arg 传递代理
docker build \
  --build-arg HTTP_PROXY=http://user:pass@proxy-host:port \
  --build-arg HTTPS_PROXY=http://user:pass@proxy-host:port \
  -t myapp .

# 在 Dockerfile 中使用 ARG 设置代理
# Dockerfile
ARG HTTP_PROXY
ARG HTTPS_PROXY
ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY

RUN npm ci

# 安装依赖后——重置代理（不要在镜像中保留！）
ENV HTTP_PROXY=""
ENV HTTPS_PROXY=""

Docker 守护进程的全局代理设置（用于 docker pull）：

# /etc/docker/daemon.json
{
  "proxies": {
    "http-proxy": "http://user:pass@proxy-host:port",
    "https-proxy": "http://user:pass@proxy-host:port",
    "no-proxy": "localhost,127.0.0.1"
  }
}

# 修改后重启 Docker
sudo systemctl restart docker

Jenkins

在 Jenkins 中，代理通过 Jenkinsfile 中的环境变量或在系统设置中全局配置：

// Jenkinsfile
pipeline {
    agent any
    
    environment {
        HTTP_PROXY  = credentials('proxy-url')
        HTTPS_PROXY = credentials('proxy-url')
        NO_PROXY    = 'localhost,127.0.0.1'
    }
    
    stages {
        stage('Install') {
            steps {
                sh 'npm config set proxy $HTTP_PROXY'
                sh 'npm config set https-proxy $HTTPS_PROXY'
                sh 'npm ci'
            }
        }
        stage('Build') {
            steps {
                sh 'npm run build'
            }
        }
    }
}

常见错误及其解决方法

即使在正确配置代理的情况下，也可能会出现问题。我们汇总了最常见的错误及其解决方案。

错误：ECONNREFUSED 或连接被拒绝

代理没有响应。原因：地址或端口错误，代理服务器不可用，凭据已过期。

解决方案： 使用以下命令检查代理的可用性：

curl -v --proxy http://user:pass@proxy-host:port https://github.com

错误：SSL 证书问题 / UNABLE_TO_VERIFY_LEAF_SIGNATURE

代理拦截 SSL 流量并插入其证书，而 Git 或 npm 不信任该证书。

Git 的解决方案：

git config --global http.sslVerify false
# 或添加代理的根证书：
git config --global http.sslCAInfo /path/to/proxy-ca.crt

错误：npm ERR! code ENOTFOUND

npm 无法解析注册表的 DNS 名称。代理已设置，但 DNS 请求未通过代理。

解决方案： 使用 SOCKS5 代替 HTTP 代理——它会隧道 DNS 请求：

npm config set proxy socks5://user:pass@proxy-host:port
npm config set https-proxy socks5://user:pass@proxy-host:port

错误：407 代理身份验证要求

代理要求身份验证，但凭据未传递或传递错误。

# 确保 URL 中的用户名和密码正确编码
# 如果密码中有特殊字符（@、:、#）——请对其进行编码：
# @ → %40, : → %3A, # → %23

# 示例：密码 "p@ss:word" → "p%40ss%3Aword"
npm config set proxy http://user:p%40ss%3Aword@proxy-host:port

Git clone 成功，但 git push 失败

Clone（读取）和 push（写入）可能使用不同的协议。确保代理同时为 HTTP 和 HTTPS 设置。如果使用 SSH 进行 push——需要在 ~/.ssh/config 中进行单独设置，如上所述。

检查清单：检查一切是否正常

设置代理后，请按照此检查清单确保一切正常工作。

✅ GitHub 和 npm 代理设置检查清单

代理可用：curl -v --proxy PROXY_URL https://github.com 返回 200
Git 配置已设置：git config --global --list | grep proxy 显示您的代理
克隆测试：git clone https://github.com/torvalds/linux.git --depth=1 成功
npm 代理已设置：npm config get proxy 显示您的代理
npm install 测试：npm install lodash 成功完成
如果使用 SSH：ssh -T [email protected] 返回欢迎信息
CI/CD：环境变量已添加到秘密中，管道通过
Docker：docker build 使用 --build-arg 成功完成，没有网络错误
速度：克隆速度明显快于没有代理时
代理凭据未以明文形式存储在代码中（仅在秘密中）

一键快速诊断

如果某些内容无法正常工作且不清楚问题所在——请运行此诊断脚本：

#!/bin/bash
# GitHub/npm 代理诊断

PROXY="http://user:pass@proxy-host:port"

echo "=== 1. 直接访问 GitHub ==="
curl -s -o /dev/null -w "%{http_code}" https://github.com && echo " OK" || echo " FAIL"

echo "=== 2. 通过代理访问 ==="
curl -s -o /dev/null -w "%{http_code}" --proxy "$PROXY" https://github.com && echo " OK" || echo " FAIL"

echo "=== 3. 通过代理访问 npm 注册表 ==="
curl -s -o /dev/null -w "%{http_code}" --proxy "$PROXY" https://registry.npmjs.org && echo " OK" || echo " FAIL"

echo "=== 4. 当前 Git 代理设置 ==="
git config --global --list | grep proxy || echo "Git 代理未设置"

echo "=== 5. 当前 npm 代理设置 ==="
npm config get proxy
npm config get https-proxy

结论

为 GitHub 和 npm 设置代理并不是一项复杂的任务，只要知道正确的步骤。让我们总结一下：

为了加速缓慢的 GitHub——适合使用美国或欧洲的数据中心代理：它们快速、稳定且价格低廉。
为了绕过封锁——住宅代理使用真实用户的 IP 提供最大可靠性。
对于通过 HTTPS 使用 Git——在 git config 中设置 http.proxy。
对于通过 SSH 使用 Git——在 ~/.ssh/config 中使用 ProxyCommand。
对于 npm/yarn/pnpm——通过配置或环境变量设置代理。
对于 CI/CD——通过秘密传递代理数据，不要硬编码在代码中。

一次性花费 10-15 分钟进行设置后，您将获得稳定的访问 GitHub 和 npm，而不必依赖于互联网连接状态或封锁政策。团队不再浪费时间等待缓慢的下载，CI/CD 管道顺利通过，而来自不同国家的开发人员在相同条件下工作。

如果您正在寻找稳定的代理以便在有限访问的国家使用 GitHub 和 npm，建议考虑数据中心代理——它们提供高速和稳定的连接，这在克隆代码库和安装依赖项时至关重要。对于有严格封锁的地区，住宅代理更为合适——它们的 IP 几乎不会受到限制。

```

GitHub和npm的代理：如何在GitHub被封锁或运行缓慢的国家访问仓库和软件包