Proxy per GitHub e npm: come accedere a repository e pacchetti da paesi con GitHub bloccato o lento

GitHub è bloccato, funziona con un ritardo di 10–30 secondi o npm install si blocca a metà strada: una situazione familiare per gli sviluppatori provenienti da Russia, Iran, Cina e altri paesi. C'è una soluzione, ed è più semplice di quanto sembri: un proxy configurato correttamente offre accesso stabile ai repository, ai pacchetti e all'API di GitHub senza VPN e senza ulteriori complicazioni.

Perché GitHub e npm bloccano o rallentano

Prima di configurare un proxy, è importante capire con cosa esattamente si sta affrontando. I problemi di accesso a GitHub e npm possono essere di tre tipi, e ognuno richiede un approccio diverso.

Blocco totale a livello statale

Alcuni paesi — Cina, Iran, Corea del Nord, e da nel 2022 occasionalmente anche la Russia — bloccano GitHub a livello DNS o per IP. Ciò significa che le richieste a github.com non passano affatto o restituiscono un errore di connessione. Il registro npm (registry.npmjs.org) può funzionare normalmente — o essere anch'esso bloccato.

Firewall aziendali e restrizioni di rete

Anche senza un blocco statale, le reti aziendali spesso limitano l'accesso a repository esterni. Questa è una pratica standard in banche, enti governativi e grandi aziende: il reparto IT chiude le connessioni in uscita su porte 443 o blocca domini specifici. Uno sviluppatore in tale rete non può eseguire git clone o npm install senza un percorso alternativo.

Velocità lenta a causa della geografia

Tecnologicamente GitHub è accessibile, ma clonare un repository di 500 MB richiede 40 minuti, e l'installazione delle dipendenze tramite npm è un'eternità. Questo è un problema di instradamento: i pacchetti passano attraverso nodi sovraccarichi o percorsi lunghi. Un server proxy situato negli Stati Uniti o in Europa accorcia il percorso e offre un reale aumento di velocità di 3–10 volte.

Proxy vs VPN: cosa scegliere per lavorare con il codice

Molti sviluppatori si rivolgono per abitudine alle VPN. Questo è comprensibile: le VPN sono semplici da configurare e funzionano immediatamente per l'intero sistema. Ma per lavorare con GitHub e npm, i proxy sono spesso più comodi. Analizziamo la differenza.

La conclusione è semplice: se il tuo obiettivo è fornire al team accesso a GitHub e npm, il proxy viene configurato una sola volta nel file di configurazione e funziona senza dover intervenire nelle impostazioni di sistema di ogni macchina. Questo è particolarmente importante per i pipeline CI/CD, dove è fisicamente difficile impostare una VPN.

Quale tipo di proxy è adatto per GitHub e npm

Non tutti i proxy funzionano altrettanto bene con Git e npm. La scelta dipende dal tuo obiettivo: aggirare il blocco, accelerare il download o lavorare da una rete aziendale.

Proxy HTTP/HTTPS

L'opzione più semplice. Git e npm supportano nativamente i proxy HTTP tramite variabili d'ambiente standard. Adatto per la maggior parte delle attività: clonazione di repository, installazione di pacchetti, lavoro con l'API di GitHub. Se il tuo provider di proxy fornisce un indirizzo HTTP, inizia da lì.

Proxy SOCKS5

Un protocollo più flessibile, funziona a livello TCP. Supporta qualsiasi tipo di traffico, comprese le connessioni SSH con GitHub (porta 22). Se utilizzi Git tramite SSH invece di HTTPS, SOCKS5 è preferibile. Git supporta SOCKS5 tramite il parametro socks5:// nel file di configurazione.

Proxy residenziali

I proxy residenziali utilizzano indirizzi IP di utenti domestici reali. Per GitHub è particolarmente rilevante se lavori da un paese con severe restrizioni: tali IP raramente finiscono nelle liste nere e appaiono come traffico utente normale. Adatti per situazioni in cui gli IP dei data center sono già bloccati a livello di provider.

Proxy di data center

I proxy di data center sono la scelta ottimale per la maggior parte degli sviluppatori. Sono più veloci dei proxy residenziali, costano meno e offrono una connessione stabile. Se GitHub è semplicemente lento e non bloccato, un proxy di data center negli Stati Uniti o in Europa offrirà il massimo aumento di velocità durante la clonazione e il download dei pacchetti.

Configurazione del proxy per Git: istruzioni passo-passo

Git supporta i proxy tramite la configurazione integrata e tramite variabili d'ambiente. Mostreremo entrambi i metodi: scegli quello che è più comodo per il tuo flusso di lavoro.

Metodo 1: Tramite git config (raccomandato)

Questa è un'impostazione permanente che si applica a tutte le operazioni Git sulla macchina. Apri il terminale ed esegui:

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

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

# Controlla che le impostazioni siano state applicate
git config --global --list | grep proxy

Sostituisci username:password@proxy-host:port con i dati del tuo proxy. Se il proxy non richiede autenticazione, rimuovi username:password@.

Metodo 2: Tramite variabili d'ambiente

Comodo per un utilizzo temporaneo o in script. Git rileva automaticamente le variabili standard HTTP_PROXY e HTTPS_PROXY:

# Linux / macOS — aggiungi in ~/.bashrc o ~/.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"

# Applica senza riavviare il terminale (Linux/macOS)
source ~/.bashrc

Configurazione del proxy solo per GitHub

Se desideri instradare tramite proxy solo le richieste a GitHub e non a tutti i repository, utilizza la configurazione sezionale:

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

# Controlla la clonazione tramite proxy
git clone https://github.com/username/repo.git

Git via SSH tramite SOCKS5

Se lavori con GitHub tramite SSH (e non HTTPS), la configurazione è leggermente diversa. Devi modificare il file ~/.ssh/config:

# ~/.ssh/config

Host github.com
    HostName github.com
    User git
    # Su Linux/macOS usa nc (netcat)
    ProxyCommand nc -X 5 -x proxy-host:port %h %p
    
    # Oppure tramite connect-proxy (deve essere installato)
    # ProxyCommand connect -S proxy-host:port %h %p
    
    # Su Windows tramite Git Bash
    # ProxyCommand connect -S proxy-host:port %h %p

Dopo di che, i comandi git clone [email protected]:user/repo.git e git push passeranno automaticamente tramite il proxy SOCKS5.

Come ripristinare le impostazioni del proxy

# Rimuovi il proxy dalla configurazione globale
git config --global --unset http.proxy
git config --global --unset https.proxy

Configurazione del proxy per npm, yarn e pnpm

Ogni gestore di pacchetti ha il proprio modo di configurare il proxy. Analizziamo tutti e tre — npm, yarn e pnpm — con comandi specifici.

npm

npm supporta il proxy tramite impostazioni integrate nella configurazione:

# Imposta il proxy per npm
npm config set proxy http://username:password@proxy-host:port
npm config set https-proxy http://username:password@proxy-host:port

# Controlla le impostazioni
npm config get proxy
npm config get https-proxy

# Test: installazione di un pacchetto tramite proxy
npm install lodash

# Ripristina il proxy
npm config delete proxy
npm config delete https-proxy

Le impostazioni vengono salvate nel file ~/.npmrc. Puoi modificarlo direttamente:

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

# Controlla
yarn config get proxy

# Ripristina
yarn config delete proxy
yarn config delete https-proxy

Yarn Berry (v2+)

# Yarn Berry utilizza variabili d'ambiente
# Aggiungi in .yarnrc.yml nella radice del progetto:
httpProxy: "http://username:password@proxy-host:port"
httpsProxy: "http://username:password@proxy-host:port"

# Oppure tramite variabili d'ambiente
export HTTP_PROXY="http://username:password@proxy-host:port"
export HTTPS_PROXY="http://username:password@proxy-host:port"

pnpm

# pnpm utilizza lo stesso .npmrc di npm
# Le impostazioni vengono applicate automaticamente se npm è già configurato

# Oppure esplicitamente tramite pnpm config
pnpm config set proxy http://username:password@proxy-host:port
pnpm config set https-proxy http://username:password@proxy-host:port

Alternativa: specchi del registro npm

Se il registro npm è lento, ma GitHub è accessibile, puoi passare a uno specchio. Opzioni popolari: Taobao (per la Cina), Verdaccio (self-hosted). Ma gli specchi spesso sono in ritardo con le versioni dei pacchetti, quindi il proxy è più affidabile:

# Passa il registro a uno specchio (solo per accelerazione, non per blocchi)
npm config set registry https://registry.npmmirror.com

# Ripristina il registro ufficiale
npm config set registry https://registry.npmjs.org

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

Configurare un proxy sulla macchina locale è solo metà del lavoro. Il vero problema inizia quando è necessario garantire accesso a GitHub e npm in un pipeline CI/CD che opera in una rete isolata. Analizziamo tre degli scenari più comuni.

GitHub Actions

In GitHub Actions, il proxy viene configurato tramite variabili d'ambiente nel file di workflow. Aggiungi i segreti nelle impostazioni del repository (Impostazioni → Segreti), quindi utilizzali nel 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

In Docker, il proxy è necessario a due livelli: durante la costruzione dell'immagine (in docker build) e all'interno del contenitore. Queste sono impostazioni diverse:

# Passa il proxy durante la costruzione tramite --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 .

# Nel Dockerfile usa ARG per il proxy
# Dockerfile
ARG HTTP_PROXY
ARG HTTPS_PROXY
ENV HTTP_PROXY=$HTTP_PROXY
ENV HTTPS_PROXY=$HTTPS_PROXY

RUN npm ci

# Dopo l'installazione delle dipendenze — ripristina il proxy (non conservarlo nell'immagine!)
ENV HTTP_PROXY=""
ENV HTTPS_PROXY=""

Impostazione globale del proxy per il demone Docker (per 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"
  }
}

# Riavvia Docker dopo le modifiche
sudo systemctl restart docker

Jenkins

In Jenkins, il proxy viene configurato a livello di agente tramite variabili d'ambiente nel Jenkinsfile o globalmente nelle impostazioni di 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'
            }
        }
    }
}

Errori comuni e come risolverli

Anche con la configurazione corretta del proxy, qualcosa potrebbe andare storto. Abbiamo raccolto gli errori più comuni e i modi per risolverli.

Errore: ECONNREFUSED o Connection refused

Il proxy non risponde. Cause: indirizzo o porta errati, server proxy non disponibile, scadenza delle credenziali.

Soluzione: Controlla la disponibilità del proxy con il comando:

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

Errore: problema con il certificato SSL / UNABLE_TO_VERIFY_LEAF_SIGNATURE

Il proxy intercetta il traffico SSL e inserisce il proprio certificato, che Git o npm non riconoscono.

Soluzione per Git:

git config --global http.sslVerify false
# Oppure aggiungi il certificato radice del proxy:
git config --global http.sslCAInfo /path/to/proxy-ca.crt

Errore: npm ERR! code ENOTFOUND

npm non riesce a risolvere il nome DNS del registro. Il proxy è configurato, ma le richieste DNS non passano attraverso di esso.

Soluzione: Usa SOCKS5 invece di un proxy HTTP: instrada le richieste DNS:

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

Errore: 407 Proxy Authentication Required

Il proxy richiede autenticazione, ma le credenziali non sono state fornite o sono state fornite in modo errato.

# Assicurati che il login e la password nell'URL siano codificati correttamente
# Se nella password ci sono caratteri speciali (@, :, #) — codificali:
# @ → %40, : → %3A, # → %23

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

Git clone funziona, ma git push no

Clone (lettura) e push (scrittura) possono utilizzare protocolli diversi. Assicurati che il proxy sia configurato sia per HTTP che per HTTPS. Se utilizzi SSH per il push, è necessaria una configurazione separata in ~/.ssh/config come descritto sopra.

Checklist: controlliamo che tutto funzioni

Dopo aver configurato il proxy, segui questa checklist per assicurarti che tutto funzioni correttamente.

Diagnostica rapida con un comando

Se qualcosa non funziona e non è chiaro dove sia il problema, esegui questo script di diagnostica:

#!/bin/bash
# Diagnostica proxy per GitHub/npm

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

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

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

echo "=== 3. Accesso al registro npm tramite proxy ==="
curl -s -o /dev/null -w "%{http_code}" --proxy "$PROXY" https://registry.npmjs.org && echo " OK" || echo " FAIL"

echo "=== 4. Impostazioni correnti del proxy Git ==="
git config --global --list | grep proxy || echo "Proxy Git non configurato"

echo "=== 5. Impostazioni correnti del proxy npm ==="
npm config get proxy
npm config get https-proxy

Conclusione

Configurare un proxy per GitHub e npm non è un compito difficile se si conosce l'ordine corretto delle operazioni. Riassumiamo:

• Per accelerare un GitHub lento — sono adatti i proxy di data center negli Stati Uniti o in Europa: sono veloci, stabili e poco costosi.
• Per aggirare i blocchi — i proxy residenziali con IP di utenti reali garantiscono la massima affidabilità.
• Per Git tramite HTTPS — configura http.proxy nel git config.
• Per Git tramite SSH — utilizza ProxyCommand in ~/.ssh/config.
• Per npm/yarn/pnpm — configura il proxy tramite config o variabili d'ambiente.
• Per CI/CD — passa i dati del proxy tramite segreti, non hardcodare nel codice.

Investendo una volta 10–15 minuti nella configurazione, ottieni accesso stabile a GitHub e npm senza dipendere dallo stato della connessione internet o dalla politica di blocco. Il team smette di perdere tempo ad aspettare caricamenti lenti, i pipeline CI/CD passano senza errori di rete e gli sviluppatori in diversi paesi lavorano nelle stesse condizioni.

Se stai cercando un proxy stabile per lavorare con GitHub e npm da paesi con accesso limitato, ti consigliamo di considerare proxy di data center — offrono alta velocità e stabilità della connessione, che è critica durante la clonazione dei repository e l'installazione delle dipendenze. Per le regioni con blocchi severi, i proxy residenziali sono più adatti: i loro IP raramente rientrano nelle restrizioni.