Proxies para GitHub e npm: como acessar repositórios e pacotes em países onde GitHub está bloqueado ou lento

O GitHub está bloqueado, funcionando com um atraso de 10 a 30 segundos ou o npm install está travado no meio do caminho — uma situação familiar para desenvolvedores da Rússia, Irã, China e vários outros países. Há uma solução, e ela é mais simples do que parece: um proxy configurado corretamente oferece acesso estável a repositórios, pacotes e API do GitHub sem VPN e sem complicações.

Por que o GitHub e npm bloqueiam ou desaceleram

Antes de configurar um proxy, é importante entender com o que exatamente você está lidando. Os problemas de acesso ao GitHub e npm podem ser de três tipos, e cada um requer uma abordagem diferente.

Bloqueio total a nível estatal

Vários países — China, Irã, Coreia do Norte, e desde 2022, ocasionalmente, a Rússia — bloqueiam o GitHub a nível de DNS ou por IP. Isso significa que as solicitações para github.com não passam de forma alguma ou retornam um erro de conexão. O registro npm (registry.npmjs.org) pode funcionar normalmente — ou também estar bloqueado.

Firewalls corporativos e restrições de rede

Mesmo sem bloqueio estatal, redes corporativas frequentemente limitam o acesso a repositórios externos. Essa é uma prática comum em bancos, instituições governamentais e grandes empresas: o departamento de TI bloqueia conexões de saída nas portas 443 ou bloqueia domínios específicos. Um desenvolvedor em tal rede não pode fazer git clone ou npm install sem um caminho alternativo.

Velocidade lenta devido à geografia

Tecnicamente, o GitHub está acessível, mas clonar um repositório de 500 MB leva 40 minutos, e a instalação de dependências via npm leva uma eternidade. Esse é um problema de roteamento: os pacotes passam por nós sobrecarregados ou rotas longas. Um servidor proxy localizado nos EUA ou na Europa encurta o caminho e proporciona um aumento real de velocidade de 3 a 10 vezes.

Proxy vs VPN: o que escolher para trabalhar com código

Muitos desenvolvedores, por hábito, recorrem ao VPN. Isso é compreensível — o VPN é fácil de configurar e funciona imediatamente para todo o sistema. Mas para trabalhar com GitHub e npm, o proxy muitas vezes é mais conveniente. Vamos analisar a diferença.

A conclusão é simples: se sua tarefa é dar à equipe acesso ao GitHub e npm, o proxy é configurado uma vez no arquivo de configuração e funciona sem interferir nas configurações do sistema de cada máquina. Isso é especialmente importante para pipelines de CI/CD, onde é fisicamente difícil levantar um VPN.

Qual tipo de proxy é adequado para GitHub e npm

Nem todos os proxies funcionam igualmente bem com Git e npm. A escolha depende da sua tarefa: contornar o bloqueio, acelerar o download ou trabalhar de uma rede corporativa.

Proxy HTTP/HTTPS

A opção mais simples. Git e npm suportam nativamente proxies HTTP através de variáveis de ambiente padrão. É adequado para a maioria das tarefas: clonagem de repositórios, instalação de pacotes, trabalho com a API do GitHub. Se o seu provedor de proxy fornece um endereço HTTP — comece por ele.

Proxy SOCKS5

Um protocolo mais flexível, funciona no nível TCP. Suporta qualquer tipo de tráfego, incluindo conexões SSH com o GitHub (porta 22). Se você usa Git via SSH, em vez de HTTPS — SOCKS5 é preferível. O Git suporta SOCKS5 através do parâmetro socks5:// na configuração.

Proxies residenciais

Proxies residenciais usam endereços IP de usuários reais. Para o GitHub, isso é especialmente relevante se você estiver trabalhando de um país com bloqueios severos: esses IPs raramente entram em listas negras e parecem tráfego de usuário normal. São adequados para situações em que os IPs de data center já estão bloqueados a nível de provedor.

Proxies de data center

Proxies de data center são a escolha ideal para a maioria dos desenvolvedores. Eles são mais rápidos que os residenciais, custam menos e oferecem uma conexão estável. Se o GitHub está apenas lento, e não bloqueado — um proxy de data center nos EUA ou Europa proporcionará o máximo aumento de velocidade ao clonar e baixar pacotes.

Configuração de proxy para Git: instruções passo a passo

O Git suporta proxy através da configuração interna e através de variáveis de ambiente. Vamos mostrar ambos os métodos — escolha o que for mais conveniente para seu fluxo de trabalho.

Método 1: Através do git config (recomendado)

Esta é uma configuração permanente que se aplica a todas as operações do Git na máquina. Abra o terminal e execute:

# Para proxy HTTP/HTTPS
git config --global http.proxy http://username:password@proxy-host:port
git config --global https.proxy http://username:password@proxy-host:port

# Para proxy SOCKS5
git config --global http.proxy socks5://username:password@proxy-host:port
git config --global https.proxy socks5://username:password@proxy-host:port

# Verifique se as configurações foram aplicadas
git config --global --list | grep proxy

Substitua username:password@proxy-host:port pelos dados do seu proxy. Se o proxy não requer autenticação — remova username:password@.

Método 2: Através de variáveis de ambiente

Conveniente para uso temporário ou em scripts. O Git automaticamente reconhece as variáveis padrão HTTP_PROXY e HTTPS_PROXY:

# Linux / macOS — adicione em ~/.bashrc ou ~/.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"

# Aplicar sem reiniciar o terminal (Linux/macOS)
source ~/.bashrc

Configuração de proxy apenas para GitHub

Se você deseja direcionar através do proxy apenas as solicitações para o GitHub, e não para todos os repositórios, use a configuração de seção:

# Proxy apenas para github.com
git config --global http.https://github.com.proxy http://username:password@proxy-host:port

# Verificação de clonagem através do proxy
git clone https://github.com/username/repo.git

Git via SSH através de SOCKS5

Se você trabalha com o GitHub via SSH (e não HTTPS), a configuração é um pouco diferente. É necessário editar o arquivo ~/.ssh/config:

# ~/.ssh/config

Host github.com
    HostName github.com
    User git
    # No Linux/macOS use nc (netcat)
    ProxyCommand nc -X 5 -x proxy-host:port %h %p
    
    # Ou através do connect-proxy (precisa ser instalado)
    # ProxyCommand connect -S proxy-host:port %h %p
    
    # No Windows através do Git Bash
    # ProxyCommand connect -S proxy-host:port %h %p

Após isso, os comandos git clone [email protected]:user/repo.git e git push serão automaticamente direcionados através do proxy SOCKS5.

Como redefinir as configurações de proxy

# Remover proxy da configuração global
git config --global --unset http.proxy
git config --global --unset https.proxy

Configuração de proxy para npm, yarn e pnpm

Cada gerenciador de pacotes tem sua própria maneira de configurar o proxy. Vamos analisar os três — npm, yarn e pnpm — com comandos específicos.

npm

O npm suporta proxy através das configurações internas do arquivo de configuração:

# Configurar proxy para npm
npm config set proxy http://username:password@proxy-host:port
npm config set https-proxy http://username:password@proxy-host:port

# Verificar configurações
npm config get proxy
npm config get https-proxy

# Teste: instalação de pacote através do proxy
npm install lodash

# Redefinir proxy
npm config delete proxy
npm config delete https-proxy

As configurações são salvas no arquivo ~/.npmrc. Você pode editá-lo diretamente:

# ~/.npmrc
proxy=http://username:password@proxy-host:port
https-proxy=http://username:password@proxy-host:port
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

# Verificar
yarn config get proxy

# Redefinir
yarn config delete proxy
yarn config delete https-proxy

Yarn Berry (v2+)

# Yarn Berry usa variáveis de ambiente
# Adicione em .yarnrc.yml na raiz do projeto:
httpProxy: "http://username:password@proxy-host:port"
httpsProxy: "http://username:password@proxy-host:port"

# Ou através de variáveis de ambiente
export HTTP_PROXY="http://username:password@proxy-host:port"
export HTTPS_PROXY="http://username:password@proxy-host:port"

pnpm

# pnpm usa o mesmo .npmrc que o npm
# As configurações são aplicadas automaticamente, se o npm já estiver configurado

# Ou explicitamente através do pnpm config
pnpm config set proxy http://username:password@proxy-host:port
pnpm config set https-proxy http://username:password@proxy-host:port

Alternativa: espelhos do registro npm

Se o registro npm estiver lento, mas o GitHub estiver acessível — você pode mudar para um espelho. Opções populares: Taobao (para a China), Verdaccio (auto-hospedado). Mas os espelhos frequentemente ficam desatualizados em relação às versões dos pacotes, portanto, o proxy é mais confiável:

# Mudar o registro para um espelho (apenas para aceleração, não para bloqueios)
npm config set registry https://registry.npmmirror.com

# Retornar ao registro oficial
npm config set registry https://registry.npmjs.org

Proxy em CI/CD: GitHub Actions, Docker, Jenkins

Configurar um proxy na máquina local é apenas metade do trabalho. A verdadeira dor começa quando é necessário garantir acesso ao GitHub e npm em um pipeline de CI/CD, que opera em uma rede isolada. Vamos analisar três dos cenários mais comuns.

GitHub Actions

No GitHub Actions, o proxy é configurado através de variáveis de ambiente no arquivo de workflow. Adicione segredos nas configurações do repositório (Configurações → Segredos), e depois use-os no workflow:

# .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

No Docker, o proxy é necessário em dois níveis: ao construir a imagem (no docker build) e dentro do contêiner. Essas são configurações diferentes:

# Passar o proxy ao construir através de --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 .

# No Dockerfile, usar ARG para o proxy
# Dockerfile
ARG HTTP_PROXY
ARG HTTPS_PROXY
ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY

RUN npm ci

# Após instalar as dependências — redefinir o proxy (não armazenar na imagem!)
ENV HTTP_PROXY=""
ENV HTTPS_PROXY=""

Configuração global do proxy para o daemon do Docker (para 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"
  }
}

# Reinicie o Docker após as alterações
sudo systemctl restart docker

Jenkins

No Jenkins, o proxy é configurado a nível de agente através de variáveis de ambiente no Jenkinsfile ou globalmente nas configurações do sistema:

// 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'
            }
        }
    }
}

Erros comuns e como corrigi-los

Mesmo com a configuração correta do proxy, algo pode dar errado. Compilamos os erros mais comuns e suas soluções.

Erro: ECONNREFUSED ou Connection refused

O proxy não responde. Causas: endereço ou porta incorretos, servidor proxy indisponível, credenciais expiradas.

Solução: Verifique a disponibilidade do proxy com o comando:

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

Erro: problema com o certificado SSL / UNABLE_TO_VERIFY_LEAF_SIGNATURE

O proxy intercepta o tráfego SSL e insere seu próprio certificado, que o Git ou npm não confiam.

Solução para Git:

git config --global http.sslVerify false
# Ou adicione o certificado raiz do proxy:
git config --global http.sslCAInfo /path/to/proxy-ca.crt

Erro: npm ERR! code ENOTFOUND

O npm não consegue resolver o nome DNS do registro. O proxy está configurado, mas as solicitações DNS não estão passando por ele.

Solução: Use SOCKS5 em vez de proxy HTTP — ele tuneliza as solicitações DNS:

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

Erro: 407 Proxy Authentication Required

O proxy requer autenticação, mas as credenciais não foram fornecidas ou foram fornecidas incorretamente.

# Certifique-se de que o login e a senha na URL estão codificados corretamente
# Se a senha contém caracteres especiais (@, :, #) — codifique-os:
# @ → %40, : → %3A, # → %23

# Exemplo: senha "p@ss:word" → "p%40ss%3Aword"
npm config set proxy http://user:p%40ss%3Aword@proxy-host:port

Git clone funciona, mas git push não

Clone (leitura) e push (gravação) podem usar protocolos diferentes. Certifique-se de que o proxy está configurado para HTTP e HTTPS. Se você usa SSH para push — uma configuração separada em ~/.ssh/config é necessária, conforme descrito acima.

Checklist: verificando se tudo funciona

Após configurar o proxy, passe por este checklist para garantir que tudo está funcionando corretamente.

Diagnóstico rápido com um comando

Se algo não estiver funcionando e você não souber onde está o problema — execute este script de diagnóstico:

#!/bin/bash
# Diagnóstico de proxy para GitHub/npm

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

echo "=== 1. Acesso direto ao GitHub ==="
curl -s -o /dev/null -w "%{http_code}" https://github.com && echo " OK" || echo " FAIL"

echo "=== 2. Acesso através do proxy ==="
curl -s -o /dev/null -w "%{http_code}" --proxy "$PROXY" https://github.com && echo " OK" || echo " FAIL"

echo "=== 3. Acesso ao registro npm através do proxy ==="
curl -s -o /dev/null -w "%{http_code}" --proxy "$PROXY" https://registry.npmjs.org && echo " OK" || echo " FAIL"

echo "=== 4. Configurações atuais do proxy do Git ==="
git config --global --list | grep proxy || echo "Proxy do Git não configurado"

echo "=== 5. Configurações atuais do proxy do npm ==="
npm config get proxy
npm config get https-proxy

Conclusão

Configurar um proxy para GitHub e npm não é uma tarefa difícil, se você souber a ordem correta das ações. Vamos resumir:

• Para acelerar um GitHub lento — proxies de data center nos EUA ou Europa são rápidos, estáveis e baratos.
• Para contornar bloqueios — proxies residenciais com IPs de usuários reais oferecem a máxima confiabilidade.
• Para Git via HTTPS — configure http.proxy no git config.
• Para Git via SSH — use ProxyCommand em ~/.ssh/config.
• Para npm/yarn/pnpm — configure o proxy através do config ou variáveis de ambiente.
• Para CI/CD — passe os dados do proxy através de segredos, não codifique no código.

Gastando uma vez de 10 a 15 minutos na configuração, você obtém acesso estável ao GitHub e npm, sem depender do estado da conexão de internet ou da política de bloqueios. A equipe para de perder tempo esperando por downloads lentos, os pipelines de CI/CD passam sem erros de rede, e desenvolvedores em diferentes países trabalham em condições iguais.

Se você está procurando um proxy estável para trabalhar com GitHub e npm de países com acesso restrito, recomendamos considerar proxies de data center — eles oferecem alta velocidade e estabilidade de conexão, o que é crítico ao clonar repositórios e instalar dependências. Para regiões com bloqueios severos, proxies residenciais são mais adequados — seus IPs praticamente não são afetados por restrições.