Come configurare un proxy per npm con blocco del registry: mirror, .npmrc e bypass delle restrizioni

```html

Il registry npm non è disponibile - e la costruzione del progetto si è bloccata. Una situazione familiare per gli sviluppatori in reti aziendali, in regioni con accesso limitato o quando si lavora attraverso un firewall rigoroso. In questa guida esamineremo tutti i metodi funzionanti: dal passaggio ai mirror alla configurazione fine del proxy in .npmrc - affinché npm install funzioni di nuovo senza errori.

Perché il registry npm è bloccato e cosa succede in questo caso

Il registry ufficiale di npm si trova all'indirizzo https://registry.npmjs.org. Si tratta di un CDN globale, ma potrebbe comunque non essere disponibile per vari motivi, e ognuno richiede un approccio specifico.

Principali motivi di indisponibilità del registry

• Firewall aziendale - l'azienda blocca le richieste dirette ai repository esterni, consentendo il traffico solo attraverso un server proxy interno. Questa è una pratica standard in banche, enti governativi e grandi aziende IT.
• Geoblocco o restrizioni regionali - in alcuni paesi e regioni, l'accesso a npmjs.org è limitato a livello di provider internet o firewall governativo.
• Rete aziendale senza accesso diretto a internet - le macchine di lavoro in segmenti isolati della rete non hanno accesso diretto a risorse esterne, tutto il traffico passa attraverso un gateway aziendale.
• Tunnel VPN con proxy forzato - la VPN aziendale reindirizza tutto il traffico, e npm non può accedere direttamente al registry.
• Problemi con l'ispezione SSL - il proxy aziendale intercetta il traffico HTTPS e sostituisce i certificati, causando errori come SELF_SIGNED_CERT_IN_CHAIN o UNABLE_TO_VERIFY_LEAF_SIGNATURE.

Errori comuni con il registry bloccato

npm ERR! code ECONNREFUSED
npm ERR! errno ECONNREFUSED
npm ERR! network request to https://registry.npmjs.org/react failed

npm ERR! code ETIMEDOUT
npm ERR! network This is a problem related to network connectivity.

npm ERR! code CERT_HAS_EXPIRED
npm ERR! code SELF_SIGNED_CERT_IN_CHAIN

Ognuno di questi codici di errore indica un problema diverso: ECONNREFUSED - connessione rifiutata dal firewall, ETIMEDOUT - la richiesta va nel nulla (bloccata senza risposta), errori di certificato - problema di ispezione SSL. Comprendere la causa restringe immediatamente il campo delle soluzioni.

Mirror del registry npm: bypass rapido senza proxy

Il modo più semplice per aggirare il blocco è passare npm a un mirror alternativo del registry. Il mirror contiene gli stessi pacchetti del registry ufficiale, ma si trova su server e domini diversi. Questo funziona quando è bloccato solo il dominio registry.npmjs.org, e non tutto il traffico HTTPS.

Mirror npm popolari

Come passare al registry

Passaggio per un singolo comando (senza modificare le impostazioni globali):

# Installazione una tantum tramite un registry alternativo
npm install react --registry https://registry.npmmirror.com

# Installare globalmente per l'utente attuale
npm config set registry https://registry.npmmirror.com

# Controllare il registry attuale
npm config get registry

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

Un aspetto importante: se si passa a un mirror in un progetto con un comando, è meglio fissarlo nel file .npmrc nella radice del repository - in questo modo tutti i membri del team riceveranno automaticamente la configurazione corretta quando clonano il progetto.

# .npmrc nella radice del progetto
registry=https://registry.npmmirror.com

Configurazione del proxy tramite .npmrc: sintassi completa

Quando il mirror non aiuta (ad esempio, tutto il traffico HTTPS esterno è bloccato), è necessario specificare esplicitamente a npm l'indirizzo del server proxy. Il file .npmrc è il principale file di configurazione di npm, ed è qui che vengono memorizzate le impostazioni del proxy.

Posizione dei file .npmrc

npm cerca la configurazione in diversi luoghi - in ordine di priorità (dal più alto al più basso):

• Progetto - /path/to/project/.npmrc - si applica solo a questo progetto
• Utente - ~/.npmrc - si applica per l'utente attuale del sistema
• Globale - $PREFIX/etc/npmrc - si applica a tutta l'installazione di npm
• Incorporato - /path/to/npm/npmrc - impostazioni predefinite di npm stesso

Sintassi per la configurazione del proxy in .npmrc

# Proxy per il traffico HTTP
proxy=http://proxy.example.com:8080

# Proxy per il traffico HTTPS (utilizzato per la maggior parte delle richieste al registry)
https-proxy=http://proxy.example.com:8080

# Proxy con autenticazione (login:password nell'URL)
proxy=http://username:[email protected]:8080
https-proxy=http://username:[email protected]:8080

# Eccezioni - indirizzi che bypassano il proxy
noproxy=localhost,127.0.0.1,internal.company.com

Impostazione del proxy tramite comandi npm config

Un'alternativa alla modifica manuale del file è l'uso del comando npm config set. Esso registrerà automaticamente le impostazioni nel file utente ~/.npmrc:

# Impostare il proxy
npm config set proxy http://proxy.example.com:8080
npm config set https-proxy http://proxy.example.com:8080

# Controllare le impostazioni correnti del proxy
npm config get proxy
npm config get https-proxy

# Rimuovere le impostazioni del proxy (ripristinare la connessione diretta)
npm config delete proxy
npm config delete https-proxy

# Visualizzare l'intera configurazione npm
npm config list

Proxy tramite variabili d'ambiente per npm

npm legge automaticamente le variabili d'ambiente di sistema standard per il proxy. Questo è utile in pipeline CI/CD, contenitori Docker e sistemi in cui la configurazione è impostata a livello di ambiente, non di file.

Variabili d'ambiente standard

# Linux / macOS - impostazione nella sessione corrente
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1

# Versioni minuscole (npm comprende entrambe)
export http_proxy=http://proxy.example.com:8080
export https_proxy=http://proxy.example.com:8080

# Windows (Command Prompt)
set HTTP_PROXY=http://proxy.example.com:8080
set HTTPS_PROXY=http://proxy.example.com:8080

# Windows (PowerShell)
$env:HTTP_PROXY = "http://proxy.example.com:8080"
$env:HTTPS_PROXY = "http://proxy.example.com:8080"

Priorità della configurazione npm

È importante comprendere che npm utilizza la seguente priorità nella determinazione del proxy (dal più alto al più basso):

1. Flag della riga di comando: --proxy http://...
2. Variabili d'ambiente con prefisso npm_config_: ad esempio, npm_config_proxy
3. File di progetto .npmrc
4. File utente ~/.npmrc
5. File globale $PREFIX/etc/npmrc
6. Variabili d'ambiente standard HTTP_PROXY / HTTPS_PROXY

Se il proxy è impostato in .npmrc, ma la variabile d'ambiente punta a un altro indirizzo - avrà la precedenza .npmrc. Questa è una causa comune di confusione nei sistemi CI/CD.

Configurazione in CI/CD (GitHub Actions, GitLab CI)

# GitHub Actions - aggiungere nella sezione env del job o step
jobs:
  build:
    runs-on: ubuntu-latest
    env:
      HTTP_PROXY: http://proxy.example.com:8080
      HTTPS_PROXY: http://proxy.example.com:8080
      NO_PROXY: localhost,127.0.0.1
    steps:
      - uses: actions/checkout@v3
      - run: npm install

# GitLab CI - nelle variabili del progetto o in .gitlab-ci.yml
variables:
  HTTP_PROXY: "http://proxy.example.com:8080"
  HTTPS_PROXY: "http://proxy.example.com:8080"

Proxy aziendale con autenticazione e ispezione SSL

I server proxy aziendali rappresentano il caso più complesso. Non solo reindirizzano il traffico, ma richiedono anche autenticazione e spesso eseguono ispezione SSL (intercettazione e decrittazione del traffico HTTPS). Questo genera errori specifici di certificato, con cui npm non è in grado di lavorare "out of the box".

Proxy con autenticazione NTLM/Basic

Se il proxy aziendale richiede un nome utente e una password (Basic Auth), è possibile passarli direttamente nell'URL. Tuttavia, con l'autenticazione NTLM (dominio Windows) è più complicato - npm non supporta NTLM nativamente. In questo caso si utilizza uno strumento intermedio.

# Basic Auth - nome utente e password nell'URL
npm config set proxy http://user:[email protected]:8080
npm config set https-proxy http://user:[email protected]:8080

# Se la password contiene caratteri speciali - devono essere URL-encoded
# @ → %40, # → %23, : → %3A
# Esempio: password "p@ss#word" → "p%40ss%23word"
npm config set proxy http://user:p%40ss%[email protected]:8080

Per l'autenticazione NTLM si utilizza l'utility cntlm - essa viene eseguita localmente, accetta normali richieste HTTP e gestisce autonomamente il handshake NTLM con il proxy aziendale. Per npm appare come un normale proxy senza autenticazione:

# Dopo la configurazione di cntlm, esso ascolta su localhost:3128
npm config set proxy http://localhost:3128
npm config set https-proxy http://localhost:3128

Risoluzione dei problemi di ispezione SSL

I proxy aziendali con ispezione SSL sostituiscono i certificati dei siti con il proprio certificato aziendale. npm verifica la catena di fiducia e rifiuta tali certificati. Ci sono tre approcci:

Metodo 1 (raccomandato): aggiungere il certificato CA aziendale ai fidati

# Ottenere il certificato aziendale dal reparto IT (file .crt o .pem)
# Specificarlo nella configurazione di npm
npm config set cafile /path/to/corporate-ca.crt

# Oppure aggiungere più certificati tramite cafile
# È possibile unire più CA in un unico file PEM

Metodo 2 (temporaneo, non sicuro): disabilitare il controllo SSL

# Utilizzare solo come soluzione temporanea per la diagnosi!
npm config set strict-ssl false

# Oppure per un singolo comando
npm install --legacy-peer-deps --no-strict-ssl

Proxy SOCKS5 per npm: configurazione tramite utility helper

npm supporta nativamente solo proxy HTTP/HTTPS. Se hai un proxy SOCKS5 (ad esempio, da un fornitore di proxy residenziali), non può essere specificato direttamente nella configurazione di npm. È necessaria uno strato intermedio - un'utility che accetta richieste HTTP da npm e le reindirizza tramite SOCKS5.

Metodo 1: proxychains (Linux/macOS)

# Installazione di proxychains
# Ubuntu/Debian:
sudo apt-get install proxychains4

# macOS:
brew install proxychains-ng

# Configurazione /etc/proxychains4.conf
[ProxyList]
socks5 proxy.example.com 1080 username password

# Esecuzione di npm tramite proxychains
proxychains4 npm install

Metodo 2: convertitore HTTP a SOCKS5 locale

L'utility privoxy o polipo crea un proxy HTTP locale che tunnelizza il traffico tramite SOCKS5. Dopo l'avvio, npm vede un normale proxy HTTP su localhost:

# Installazione di privoxy
sudo apt-get install privoxy  # Ubuntu/Debian
brew install privoxy          # macOS

# Aggiungere nella configurazione /etc/privoxy/config:
forward-socks5 / proxy.example.com:1080 .

# Privoxy ascolta su localhost:8118 per impostazione predefinita
# Specificare a npm di utilizzare questo indirizzo:
npm config set proxy http://localhost:8118
npm config set https-proxy http://localhost:8118

Metodo 3: tunnel SSH come proxy SOCKS5

Se hai accesso a un server remoto con internet aperto, puoi creare un tunnel SSH SOCKS5 e reindirizzare il traffico npm attraverso di esso. Questo è particolarmente utile quando si lavora da una rete aziendale con accesso limitato:

# Creare un tunnel SSH SOCKS5 sulla porta locale 1080
ssh -D 1080 -f -C -q -N [email protected]

# Successivamente utilizzare privoxy o proxychains per convertire in HTTP
# Oppure direttamente tramite variabile d'ambiente (Node.js comprende SOCKS tramite alcune librerie)

# Alternativa - utilizzare curl come test:
curl --socks5 localhost:1080 https://registry.npmjs.org/react/latest

Registry privato come alternativa al proxy

In ambienti aziendali e isolati, spesso la soluzione migliore non è configurare un proxy per ogni sviluppatore, ma implementare un proprio npm-registry all'interno della rete. Questo registry memorizza nella cache i pacchetti da npmjs.org pubblico e li fornisce dalla rete interna. Gli sviluppatori non hanno bisogno di accesso a internet - tutto funziona tramite il registry locale.

Verdaccio: avvio rapido in 10 minuti

Verdaccio è un npm-registry open source con supporto per proxy e caching. Si installa come pacchetto npm e funziona come servizio separato:

# Installazione di Verdaccio globalmente
npm install -g verdaccio

# Avvio (per impostazione predefinita ascolta su http://localhost:4873)
verdaccio

# Configurazione di npm per utilizzare il registry locale
npm config set registry http://localhost:4873

# Pubblicazione di pacchetti nel registry locale
npm adduser --registry http://localhost:4873
npm publish --registry http://localhost:4873

La configurazione di Verdaccio (~/.config/verdaccio/config.yaml) consente di configurare il proxy tramite un proxy esterno per scaricare pacchetti da npmjs.org:

# config.yaml - configurazione uplink con proxy
uplinks:
  npmjs:
    url: https://registry.npmjs.org/
    # Se Verdaccio si trova dietro un proxy:
    agent_options:
      http_proxy: http://proxy.company.com:8080
      https_proxy: http://proxy.company.com:8080
      no_proxy: localhost,127.0.0.1

packages:
  '@*/*':
    access: $all
    publish: $authenticated
    proxy: npmjs
  '**':
    access: $all
    publish: $authenticated
    proxy: npmjs

Confronto delle soluzioni per ambienti isolati

Diagnosi e risoluzione di errori comuni

Anche dopo una corretta configurazione, potrebbero sorgere problemi con il proxy. Ecco un approccio sistematico alla diagnosi e un elenco degli errori più comuni con le loro soluzioni.

Passo 1: Controllare la configurazione attuale di npm

# Mostrare tutte le impostazioni di npm (inclusi i proxy)
npm config list

# Mostrare solo le impostazioni del proxy
npm config get proxy
npm config get https-proxy
npm config get registry
npm config get strict-ssl

# Abilitare l'output dettagliato per la diagnosi
npm install react --verbose
npm install react --loglevel verbose

Passo 2: Controllare la disponibilità del registry direttamente

# Controllare la disponibilità del registry tramite curl
curl -v https://registry.npmjs.org/react/latest

# Controllare tramite proxy
curl -v --proxy http://proxy.example.com:8080 https://registry.npmjs.org/react/latest

# Controllare ping (non sempre informativo per HTTPS)
ping registry.npmjs.org

# Controllare la risoluzione DNS
nslookup registry.npmjs.org

Errori comuni e le loro soluzioni

Ripristino di tutte le impostazioni del proxy

# Rimuovere tutte le impostazioni del proxy dalla configurazione utente
npm config delete proxy
npm config delete https-proxy
npm config delete noproxy

# Ripristinare il registry a quello ufficiale
npm config set registry https://registry.npmjs.org

# Ripristinare strict-ssl (se disabilitato)
npm config set strict-ssl true

# Controllare la configurazione finale
npm config list

Lavorare con pnpm e Yarn in caso di registry bloccato

Se utilizzi gestori di pacchetti alternativi, la configurazione del proxy appare simile, ma la sintassi è leggermente diversa:

# pnpm - utilizza lo stesso .npmrc di npm
# In aggiunta, puoi configurare tramite pnpm config:
pnpm config set proxy http://proxy.example.com:8080
pnpm config set https-proxy http://proxy.example.com:8080
pnpm config set registry https://registry.npmmirror.com

# Yarn Classic (v1) - proprio file .yarnrc
yarn config set proxy http://proxy.example.com:8080
yarn config set https-proxy http://proxy.example.com:8080
yarn config set registry https://registry.npmmirror.com

# Yarn Berry (v2+) - file .yarnrc.yml
# httpProxy: "http://proxy.example.com:8080"
# httpsProxy: "http://proxy.example.com:8080"
# npmRegistryServer: "https://registry.npmmirror.com"

Configurazione del proxy per pacchetti scoped specifici

A volte è necessario utilizzare registry diversi per pacchetti diversi: ad esempio, prelevare pacchetti pubblici da npmjs.org ufficiale, e pacchetti aziendali @company/* da Nexus interno. Questo si configura tramite registry specifici per scope in .npmrc:

# .npmrc - registry diversi per diversi scope
registry=https://registry.npmjs.org

# Pacchetti aziendali @company tramite Nexus interno
@company:registry=http://nexus.company.local/repository/npm-hosted/

# Pacchetti @myorg tramite Verdaccio
@myorg:registry=http://localhost:4873/

# Autenticazione per un registry specifico
//nexus.company.local/repository/npm-hosted/:_authToken=YOUR_TOKEN_HERE

Conclusione e raccomandazioni finali

In conclusione, la configurazione di un proxy per npm in caso di blocco del registry richiede attenzione ai dettagli e una comprensione chiara delle varie opzioni disponibili. Utilizzando i mirror, configurando correttamente il file .npmrc e gestendo le variabili d'ambiente, gli sviluppatori possono garantire un flusso di lavoro continuo e senza interruzioni. È fondamentale testare le configurazioni e monitorare eventuali problemi di connessione per ottimizzare l'esperienza di sviluppo.