Comment configurer un proxy pour npm en cas de blocage du registre : miroirs, .npmrc et contournement des restrictions

```html

Le registre npm est inaccessible - et la construction du projet est bloquée. Une situation familière pour les développeurs dans des réseaux d'entreprise, des régions à accès limité ou lors de l'utilisation d'un pare-feu strict. Dans ce guide, nous examinerons toutes les méthodes fonctionnelles : du passage aux miroirs à la configuration fine du proxy dans .npmrc - afin que npm install fonctionne à nouveau sans erreurs.

Pourquoi le registre npm est-il bloqué et que se passe-t-il ?

Le registre officiel npm est situé à l'adresse https://registry.npmjs.org. C'est un CDN mondial, mais il peut tout de même être inaccessible pour plusieurs raisons, et chacune nécessite une approche différente.

Principales raisons de l'inaccessibilité du registre

• Pare-feu d'entreprise - l'entreprise bloque les requêtes directes vers des dépôts externes, autorisant le trafic uniquement via un serveur proxy interne. C'est une pratique standard dans les banques, les organismes gouvernementaux et les grandes entreprises informatiques.
• Géoblocage ou restrictions régionales - dans certains pays et régions, l'accès à npmjs.org est limité au niveau du fournisseur d'accès Internet ou du pare-feu gouvernemental.
• Réseau de bureau sans accès direct à Internet - les machines de travail dans des segments de réseau isolés n'ont pas d'accès direct aux ressources externes, tout le trafic passe par une passerelle d'entreprise.
• Tunnel VPN avec proxy forcé - le VPN d'entreprise redirige tout le trafic, et npm ne peut pas accéder directement au registre.
• Problèmes d'inspection SSL - le proxy d'entreprise intercepte le trafic HTTPS et remplace les certificats, ce qui entraîne des erreurs telles que SELF_SIGNED_CERT_IN_CHAIN ou UNABLE_TO_VERIFY_LEAF_SIGNATURE.

Erreurs typiques lors du blocage du registre

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

Chacun de ces codes d'erreur indique un problème différent : ECONNREFUSED - connexion refusée par le pare-feu, ETIMEDOUT - la requête se perd sans réponse (bloquée), les erreurs de certificat - problème d'inspection SSL. Comprendre la cause réduit immédiatement le champ des solutions.

Miroirs du registre npm : contournement rapide sans proxy

Le moyen le plus simple de contourner le blocage consiste à passer npm à un miroir alternatif du registre. Le miroir contient les mêmes paquets que le registre officiel, mais est situé sur d'autres serveurs et domaines. Cela fonctionne lorsque seul le domaine registry.npmjs.org est bloqué, et non tout le trafic HTTPS.

Miroirs npm populaires

Comment changer de registre

Changement pour une seule commande (sans modifier les paramètres globaux) :

# Installation unique via un registre alternatif
npm install react --registry https://registry.npmmirror.com

# Installer globalement pour l'utilisateur actuel
npm config set registry https://registry.npmmirror.com

# Vérifier le registre actuel
npm config get registry

# Retourner au registre officiel
npm config set registry https://registry.npmjs.org

Un point important : si vous passez à un miroir dans un projet avec une commande, il est préférable de le fixer dans le fichier .npmrc à la racine du dépôt - alors tous les membres de l'équipe recevront automatiquement la bonne configuration lors du clonage du projet.

# .npmrc à la racine du projet
registry=https://registry.npmmirror.com

Configuration du proxy via .npmrc : syntaxe complète

Lorsque le miroir ne fonctionne pas (par exemple, si tout le trafic HTTPS externe est bloqué), il faut indiquer explicitement à npm l'adresse du serveur proxy. Le fichier .npmrc est le fichier de configuration principal de npm, et c'est là que sont stockés les paramètres du proxy.

Emplacement des fichiers .npmrc

npm recherche la configuration à plusieurs endroits - par ordre de priorité (du plus élevé au plus bas) :

• Projet - /path/to/project/.npmrc - s'applique uniquement à ce projet
• Utilisateur - ~/.npmrc - s'applique à l'utilisateur actuel du système
• Global - $PREFIX/etc/npmrc - s'applique à toute l'installation de npm
• Intégré - /path/to/npm/npmrc - paramètres par défaut de npm lui-même

Syntaxe de configuration du proxy dans .npmrc

# Proxy pour le trafic HTTP
proxy=http://proxy.example.com:8080

# Proxy pour le trafic HTTPS (utilisé pour la plupart des requêtes vers le registre)
https-proxy=http://proxy.example.com:8080

# Proxy avec authentification (login:motdepasse dans l'URL)
proxy=http://username:[email protected]:8080
https-proxy=http://username:[email protected]:8080

# Exceptions - adresses qui contournent le proxy
noproxy=localhost,127.0.0.1,internal.company.com

Configuration du proxy via les commandes npm config

Une alternative à l'édition manuelle du fichier est d'utiliser la commande npm config set. Cela enregistrera automatiquement les paramètres dans le fichier utilisateur ~/.npmrc :

# Configurer le proxy
npm config set proxy http://proxy.example.com:8080
npm config set https-proxy http://proxy.example.com:8080

# Vérifier les paramètres actuels du proxy
npm config get proxy
npm config get https-proxy

# Supprimer les paramètres du proxy (retourner à la connexion directe)
npm config delete proxy
npm config delete https-proxy

# Voir toute la configuration npm
npm config list

Proxy via des variables d'environnement pour npm

npm lit automatiquement les variables d'environnement système standard pour le proxy. C'est pratique dans les pipelines CI/CD, les conteneurs Docker et les systèmes où la configuration est définie au niveau de l'environnement, et non des fichiers.

Variables d'environnement standard

# Linux / macOS - configuration dans la session actuelle
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1

# Variantes en minuscules (npm comprend les deux)
export http_proxy=http://proxy.example.com:8080
export https_proxy=http://proxy.example.com:8080

# Windows (Invite de commandes)
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é de la configuration npm

Il est important de comprendre que npm utilise la priorité suivante pour déterminer le proxy (du plus élevé au plus bas) :

1. Flags de ligne de commande : --proxy http://...
2. Variables d'environnement avec le préfixe npm_config_ : par exemple, npm_config_proxy
3. Fichier de projet .npmrc
4. Fichier utilisateur ~/.npmrc
5. Fichier global $PREFIX/etc/npmrc
6. Variables d'environnement standard HTTP_PROXY / HTTPS_PROXY

Si le proxy est configuré dans .npmrc, mais que la variable d'environnement pointe vers une autre adresse - .npmrc l'emportera. C'est une cause fréquente de confusion dans les systèmes CI/CD.

Configuration dans CI/CD (GitHub Actions, GitLab CI)

# GitHub Actions - ajouter dans la section env du job ou de l'étape
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 - dans les variables du projet ou dans .gitlab-ci.yml
variables:
  HTTP_PROXY: "http://proxy.example.com:8080"
  HTTPS_PROXY: "http://proxy.example.com:8080"

Proxy d'entreprise avec authentification et inspection SSL

Les serveurs proxy d'entreprise sont le cas le plus complexe. Ils ne se contentent pas de rediriger le trafic, mais nécessitent également une authentification, et effectuent souvent une inspection SSL (interception et déchiffrement du trafic HTTPS). Cela entraîne des erreurs de certificat spécifiques, que npm ne sait pas gérer par défaut.

Proxy avec authentification NTLM/Basic

Si le proxy d'entreprise nécessite un login et un mot de passe (Basic Auth), ils peuvent être passés directement dans l'URL. Cependant, avec l'authentification NTLM (domaine Windows), c'est plus compliqué - npm ne prend pas en charge NTLM nativement. Dans ce cas, un outil intermédiaire est utilisé.

# Basic Auth - login et mot de passe dans l'URL
npm config set proxy http://user:[email protected]:8080
npm config set https-proxy http://user:[email protected]:8080

# Si le mot de passe contient des caractères spéciaux, ils doivent être encodés en URL
# @ → %40, # → %23, : → %3A
# Exemple : mot de passe "p@ss#word" → "p%40ss%23word"
npm config set proxy http://user:p%40ss%[email protected]:8080

Pour l'authentification NTLM, on utilise l'outil cntlm - il s'exécute localement, accepte des requêtes HTTP normales et effectue lui-même le handshake NTLM avec le proxy d'entreprise. Pour npm, cela ressemble à un proxy ordinaire sans authentification :

# Après la configuration de cntlm, il écoute sur localhost:3128
npm config set proxy http://localhost:3128
npm config set https-proxy http://localhost:3128

Résolution du problème d'inspection SSL

Les proxies d'entreprise avec inspection SSL remplacent les certificats des sites par leur certificat d'entreprise. npm vérifie la chaîne de confiance et rejette ces certificats. Il existe trois approches :

Méthode 1 (recommandée) : ajouter le certificat CA d'entreprise aux certificats de confiance

# Obtenir le certificat d'entreprise auprès du service informatique (fichier .crt ou .pem)
# L'indiquer dans la configuration npm
npm config set cafile /path/to/corporate-ca.crt

# Ou ajouter plusieurs certificats via cafile
# Plusieurs CA peuvent être combinés dans un seul fichier PEM

Méthode 2 (temporaire, non sécurisée) : désactiver la vérification SSL

# Utiliser uniquement comme solution temporaire pour le diagnostic !
npm config set strict-ssl false

# Ou pour une seule commande
npm install --legacy-peer-deps --no-strict-ssl

Proxy SOCKS5 pour npm : configuration via des utilitaires d'aide

npm prend en charge uniquement les proxies HTTP/HTTPS par défaut. Si vous avez un proxy SOCKS5 (par exemple, d'un fournisseur de proxies résidentiels), il ne peut pas être spécifié directement dans la configuration npm. Un intermédiaire est nécessaire - un utilitaire qui accepte les requêtes HTTP de npm et les redirige via SOCKS5.

Méthode 1 : proxychains (Linux/macOS)

# Installation de proxychains
# Ubuntu/Debian :
sudo apt-get install proxychains4

# macOS :
brew install proxychains-ng

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

# Lancer npm via proxychains
proxychains4 npm install

Méthode 2 : convertisseur HTTP vers SOCKS5 local

L'utilitaire privoxy ou polipo crée un proxy HTTP local qui tunnelise le trafic via SOCKS5. Après son lancement, npm voit un proxy HTTP ordinaire à localhost :

# Installation de privoxy
sudo apt-get install privoxy  # Ubuntu/Debian
brew install privoxy          # macOS

# Ajouter dans la configuration /etc/privoxy/config :
forward-socks5 / proxy.example.com:1080 .

# Privoxy écoute par défaut sur localhost:8118
# Indiquer à npm d'utiliser cette adresse :
npm config set proxy http://localhost:8118
npm config set https-proxy http://localhost:8118

Méthode 3 : tunnel SSH comme proxy SOCKS5

Si vous avez accès à un serveur distant avec un accès Internet ouvert, vous pouvez créer un tunnel SSH SOCKS5 et diriger le trafic npm à travers celui-ci. C'est particulièrement pratique lorsque vous travaillez depuis un réseau d'entreprise avec un accès limité :

# Créer un tunnel SSH SOCKS5 sur le port local 1080
ssh -D 1080 -f -C -q -N [email protected]

# Ensuite, utiliser privoxy ou proxychains pour la conversion en HTTP
# Ou directement via une variable d'environnement (Node.js comprend SOCKS via certaines bibliothèques)

# Alternative - utiliser curl comme test :
curl --socks5 localhost:1080 https://registry.npmjs.org/react/latest

Registre privé comme alternative au proxy

Dans des environnements d'entreprise et isolés, la meilleure solution consiste souvent non pas à configurer un proxy pour chaque développeur, mais à déployer son propre registre npm à l'intérieur du réseau. Ce registre met en cache les paquets de npmjs.org et les fournit depuis le réseau interne. Les développeurs n'ont pas besoin d'accès à Internet - tout fonctionne via le registre local.

Verdaccio : démarrage rapide en 10 minutes

Verdaccio est un registre npm open source avec prise en charge du proxy et de la mise en cache. Il s'installe comme un paquet npm et fonctionne comme un service distinct :

# Installation de Verdaccio globalement
npm install -g verdaccio

# Lancement (écoute par défaut sur http://localhost:4873)
verdaccio

# Configuration de npm pour utiliser le registre local
npm config set registry http://localhost:4873

# Publication de paquets dans le registre local
npm adduser --registry http://localhost:4873
npm publish --registry http://localhost:4873

La configuration de Verdaccio (~/.config/verdaccio/config.yaml) permet de configurer le proxy via un proxy externe pour télécharger des paquets depuis npmjs.org :

# config.yaml - configuration uplink avec proxy
uplinks:
  npmjs:
    url: https://registry.npmjs.org/
    # Si Verdaccio se trouve lui-même derrière 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

Comparaison des solutions pour des environnements isolés

Diagnostic et résolution des erreurs courantes

Même après une configuration correcte, des problèmes peuvent survenir avec le proxy. Voici une approche systématique pour le diagnostic et une liste des erreurs les plus fréquentes avec leurs solutions.

Étape 1 : Vérifier la configuration actuelle de npm

# Afficher tous les paramètres npm (y compris le proxy)
npm config list

# Afficher uniquement les paramètres du proxy
npm config get proxy
npm config get https-proxy
npm config get registry
npm config get strict-ssl

# Activer la sortie détaillée pour le diagnostic
npm install react --verbose
npm install react --loglevel verbose

Étape 2 : Vérifier l'accessibilité du registre directement

# Vérifier l'accessibilité du registre via curl
curl -v https://registry.npmjs.org/react/latest

# Vérifier via le proxy
curl -v --proxy http://proxy.example.com:8080 https://registry.npmjs.org/react/latest

# Vérifier le ping (pas toujours informatif pour HTTPS)
ping registry.npmjs.org

# Vérifier la résolution DNS
nslookup registry.npmjs.org

Erreurs typiques et leurs solutions

Réinitialiser tous les paramètres du proxy

# Supprimer tous les paramètres du proxy de la configuration utilisateur
npm config delete proxy
npm config delete https-proxy
npm config delete noproxy

# Réinitialiser le registre au registre officiel
npm config set registry https://registry.npmjs.org

# Retourner strict-ssl (si désactivé)
npm config set strict-ssl true

# Vérifier la configuration finale
npm config list

Travailler avec pnpm et Yarn lors du blocage du registre

Si vous utilisez des gestionnaires de paquets alternatifs, la configuration du proxy ressemble à celle de npm, mais la syntaxe diffère légèrement :

# pnpm - utilise le même .npmrc que npm
# En plus, vous pouvez configurer via 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) - son propre fichier .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+) - fichier .yarnrc.yml
# httpProxy: "http://proxy.example.com:8080"
# httpsProxy: "http://proxy.example.com:8080"
# npmRegistryServer: "https://registry.npmmirror.com"

Configuration du proxy pour des paquets spécifiques à un scope

Parfois, il est nécessaire d'utiliser différents registres pour différents paquets : par exemple, prendre des paquets publics depuis le npmjs.org officiel, et des paquets d'entreprise @company/* depuis un Nexus interne. Cela se configure via un registre spécifique au scope dans .npmrc :

# .npmrc - différents registres pour différents scopes
registry=https://registry.npmjs.org

# Paquets d'entreprise @company via Nexus interne
@company:registry=http://nexus.company.local/repository/npm-hosted/

# Paquets @myorg via Verdaccio
@myorg:registry=http://localhost:4873/

# Authentification pour un registre spécifique
//nexus.company.local/repository/npm-hosted/:_authToken=YOUR_TOKEN_HERE

Conclusion et recommandations finales

Dans cet article, nous avons exploré diverses méthodes pour configurer un proxy pour npm lors du blocage du registre. Que vous choisissiez d'utiliser des miroirs, de configurer un proxy via .npmrc ou d'installer un registre privé, il est essentiel de comprendre votre environnement réseau et les exigences de votre projet. En suivant ces recommandations, vous serez en mesure de surmonter les obstacles liés à l'accès au registre npm et d'assurer un flux de travail de développement fluide.