Cómo configurar un proxy para npm al bloquear el registro: espejos, .npmrc y cómo sortear restricciones

```html

npm-registry no está disponible — y la construcción del proyecto se ha detenido por completo. Una situación familiar para los desarrolladores en redes corporativas, regiones con acceso restringido o al trabajar a través de un firewall estricto. En esta guía, analizaremos todas las formas de trabajo: desde cambiar a espejos hasta la configuración detallada del proxy en .npmrc — para que npm install funcione nuevamente sin errores.

Por qué se bloquea el registro de npm y qué sucede en este caso

El registro oficial de npm se encuentra en https://registry.npmjs.org. Es un CDN global, pero aún puede no estar disponible por varias razones, y cada una requiere un enfoque diferente.

Principales razones de la inaccesibilidad del registro

• Firewall corporativo — la empresa bloquea solicitudes directas a repositorios externos, permitiendo tráfico solo a través de un servidor proxy interno. Esta es una práctica estándar en bancos, entidades gubernamentales y grandes empresas de TI.
• Geobloqueo o restricciones regionales — en varios países y regiones, el acceso a npmjs.org está restringido a nivel de proveedor de internet o firewall gubernamental.
• Red de oficina sin salida directa a internet — las máquinas de trabajo en segmentos aislados de la red no tienen acceso directo a recursos externos, todo el tráfico pasa a través de una puerta de enlace corporativa.
• Túnel VPN con proxy forzado — la VPN corporativa redirige todo el tráfico, y npm no puede acceder al registro directamente.
• Problemas con la inspección SSL — el proxy corporativo intercepta el tráfico HTTPS y reemplaza los certificados, lo que provoca errores como SELF_SIGNED_CERT_IN_CHAIN o UNABLE_TO_VERIFY_LEAF_SIGNATURE.

Errores comunes al bloquear el registro

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

Cada uno de estos códigos de error indica un problema diferente: ECONNREFUSED — conexión rechazada por el firewall, ETIMEDOUT — la solicitud se pierde (bloqueada sin respuesta), errores de certificados — problema de inspección SSL. Comprender la causa inmediatamente reduce el rango de soluciones.

Espejos del registro de npm: una forma rápida de eludir sin proxy

La forma más sencilla de eludir el bloqueo es cambiar npm a un espejo alternativo del registro. El espejo contiene los mismos paquetes que el registro oficial, pero se encuentra en otros servidores y dominios. Esto funciona cuando se bloquea específicamente el dominio registry.npmjs.org, y no todo el tráfico HTTPS.

Espejos populares de npm

Cómo cambiar el registro

Cambio para un solo comando (sin modificar la configuración global):

# Instalación única a través de un registro alternativo
npm install react --registry https://registry.npmmirror.com

# Instalar globalmente para el usuario actual
npm config set registry https://registry.npmmirror.com

# Verificar el registro actual
npm config get registry

# Volver al registro oficial
npm config set registry https://registry.npmjs.org

Un matiz importante: si cambias a un espejo en un proyecto con un comando, es mejor fijar esto en el archivo .npmrc en la raíz del repositorio — así todos los miembros del equipo obtendrán automáticamente la configuración correcta al clonar el proyecto.

# .npmrc en la raíz del proyecto
registry=https://registry.npmmirror.com

Configuración del proxy a través de .npmrc: sintaxis completa

Cuando el espejo no ayuda (por ejemplo, todo el tráfico HTTPS externo está bloqueado), es necesario indicar explícitamente a npm la dirección del servidor proxy. El archivo .npmrc es el archivo de configuración principal de npm, y es donde se almacenan las configuraciones del proxy.

Ubicación de los archivos .npmrc

npm busca la configuración en varios lugares — en orden de prioridad (de mayor a menor):

• Proyecto — /path/to/project/.npmrc — se aplica solo a este proyecto
• Usuario — ~/.npmrc — se aplica para el usuario actual del sistema
• Global — $PREFIX/etc/npmrc — se aplica a toda la instalación de npm
• Incorporado — /path/to/npm/npmrc — configuraciones predeterminadas de npm

Sintaxis de configuración del proxy en .npmrc

# Proxy para tráfico HTTP
proxy=http://proxy.example.com:8080

# Proxy para tráfico HTTPS (utilizado para la mayoría de las solicitudes al registro)
https-proxy=http://proxy.example.com:8080

# Proxy con autenticación (usuario:contraseña en la URL)
proxy=http://username:[email protected]:8080
https-proxy=http://username:[email protected]:8080

# Excepciones — direcciones que evitan el proxy
noproxy=localhost,127.0.0.1,internal.company.com

Configuración del proxy a través de comandos npm config

Una alternativa a la edición manual del archivo es usar el comando npm config set. Este comando escribirá automáticamente la configuración en el ~/.npmrc del usuario:

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

# Verificar la configuración actual del proxy
npm config get proxy
npm config get https-proxy

# Eliminar la configuración del proxy (volver a la conexión directa)
npm config delete proxy
npm config delete https-proxy

# Ver toda la configuración de npm
npm config list

Proxy a través de variables de entorno para npm

npm lee automáticamente las variables de entorno estándar del sistema para el proxy. Esto es conveniente en pipelines de CI/CD, contenedores Docker y sistemas donde la configuración se establece a nivel de entorno, no de archivos.

Variables de entorno estándar

# Linux / macOS — configuración en la sesión actual
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 minúsculas (npm entiende ambas)
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"

Prioridad de configuración de npm

Es importante entender que npm utiliza la siguiente prioridad al determinar el proxy (de mayor a menor):

1. Flags de línea de comandos: --proxy http://...
2. Variables de entorno con el prefijo npm_config_: por ejemplo, npm_config_proxy
3. Archivo de proyecto .npmrc
4. Archivo de usuario ~/.npmrc
5. Archivo global $PREFIX/etc/npmrc
6. Variables de entorno estándar HTTP_PROXY / HTTPS_PROXY

Si el proxy está configurado en .npmrc, pero la variable de entorno apunta a otra dirección, ganará .npmrc. Esta es una causa común de confusión en sistemas de CI/CD.

Configuración en CI/CD (GitHub Actions, GitLab CI)

# GitHub Actions — agregar en la sección 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 — en las variables del proyecto o en .gitlab-ci.yml
variables:
  HTTP_PROXY: "http://proxy.example.com:8080"
  HTTPS_PROXY: "http://proxy.example.com:8080"

Proxy corporativo con autenticación y SSL-inspección

Los servidores proxy corporativos son el caso más complicado. No solo redirigen el tráfico, sino que también requieren autenticación, y a menudo realizan inspección SSL (interceptación y descifrado del tráfico HTTPS). Esto genera errores específicos de certificados que npm no puede manejar de forma nativa.

Proxy con autenticación NTLM/Basic

Si el proxy corporativo requiere un nombre de usuario y una contraseña (Autenticación Básica), se pueden pasar directamente en la URL. Sin embargo, con la autenticación NTLM (dominio de Windows) es más complicado — npm no soporta NTLM de forma nativa. En este caso, se utiliza una herramienta intermedia.

# Autenticación Básica — nombre de usuario y contraseña en la URL
npm config set proxy http://user:[email protected]:8080
npm config set https-proxy http://user:[email protected]:8080

# Si la contraseña contiene caracteres especiales, deben ser codificados en URL
# @ → %40, # → %23, : → %3A
# Ejemplo: contraseña "p@ss#word" → "p%40ss%23word"
npm config set proxy http://user:p%40ss%[email protected]:8080

Para la autenticación NTLM, se utiliza la utilidad cntlm — se ejecuta localmente, acepta solicitudes HTTP normales y realiza el apretón de manos NTLM con el proxy corporativo. Para npm, esto se ve como un proxy normal sin autenticación:

# Después de configurar cntlm, escucha en localhost:3128
npm config set proxy http://localhost:3128
npm config set https-proxy http://localhost:3128

Solución al problema de la inspección SSL

Los proxies corporativos con inspección SSL reemplazan los certificados de los sitios por su certificado corporativo. npm verifica la cadena de confianza y rechaza esos certificados. Hay tres enfoques:

Forma 1 (recomendada): agregar el certificado CA corporativo a los confiables

# Obtener el certificado corporativo del departamento de TI (archivo .crt o .pem)
# Especificarlo en la configuración de npm
npm config set cafile /path/to/corporate-ca.crt

# O agregar varios certificados a través de cafile
# Se pueden combinar varios CA en un solo archivo PEM

Forma 2 (temporal, insegura): desactivar la verificación SSL

# Usar solo como solución temporal para diagnóstico!
npm config set strict-ssl false

# O para un solo comando
npm install --legacy-peer-deps --no-strict-ssl

Proxy SOCKS5 para npm: configuración a través de utilidades helper

npm solo admite de forma nativa proxies HTTP/HTTPS. Si tiene un proxy SOCKS5 (por ejemplo, de un proveedor de proxies residenciales), no se puede especificar directamente en la configuración de npm. Se necesita una capa intermedia: una utilidad que acepte solicitudes HTTP de npm y las redirija a través de SOCKS5.

Forma 1: proxychains (Linux/macOS)

# Instalación de proxychains
# Ubuntu/Debian:
sudo apt-get install proxychains4

# macOS:
brew install proxychains-ng

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

# Ejecutar npm a través de proxychains
proxychains4 npm install

Forma 2: convertidor local HTTP a SOCKS5

La utilidad privoxy o polipo crea un proxy HTTP local que tuneliza el tráfico a través de SOCKS5. Después de iniciar, npm verá un proxy HTTP normal en localhost:

# Instalación de privoxy
sudo apt-get install privoxy  # Ubuntu/Debian
brew install privoxy          # macOS

# Agregar a la configuración /etc/privoxy/config:
forward-socks5 / proxy.example.com:1080 .

# Privoxy escucha en localhost:8118 por defecto
# Indicar a npm que use esta dirección:
npm config set proxy http://localhost:8118
npm config set https-proxy http://localhost:8118

Forma 3: túnel SSH como proxy SOCKS5

Si tiene acceso a un servidor remoto con internet abierto, puede crear un túnel SSH SOCKS5 y redirigir el tráfico de npm a través de él. Esto es especialmente conveniente al trabajar desde una red corporativa con acceso restringido:

# Crear un túnel SSH SOCKS5 en el puerto local 1080
ssh -D 1080 -f -C -q -N [email protected]

# Luego usar privoxy o proxychains para convertir a HTTP
# O directamente a través de la variable de entorno (Node.js entiende SOCKS a través de algunas bibliotecas)

# Alternativa — usar curl como prueba:
curl --socks5 localhost:1080 https://registry.npmjs.org/react/latest

Registro privado propio como alternativa al proxy

En entornos corporativos y aislados, a menudo la mejor solución no es configurar un proxy para cada desarrollador, sino desplegar un registro npm propio dentro de la red. Este registro almacena en caché paquetes de npmjs.org y los entrega desde la red interna. Los desarrolladores no necesitan acceso a internet — todo funciona a través del registro local.

Verdaccio: inicio rápido en 10 minutos

Verdaccio es un registro npm de código abierto que soporta proxy y almacenamiento en caché. Se instala como un paquete npm y funciona como un servicio separado:

# Instalación de Verdaccio globalmente
npm install -g verdaccio

# Iniciar (por defecto escucha en http://localhost:4873)
verdaccio

# Configurar npm para usar el registro local
npm config set registry http://localhost:4873

# Publicar paquetes en el registro local
npm adduser --registry http://localhost:4873
npm publish --registry http://localhost:4873

La configuración de Verdaccio (~/.config/verdaccio/config.yaml) permite configurar el proxy a través de un proxy externo para descargar paquetes de npmjs.org:

# config.yaml — configuración uplink con proxy
uplinks:
  npmjs:
    url: https://registry.npmjs.org/
    # Si Verdaccio está detrás de 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

Comparación de soluciones para entornos aislados

Diagnóstico y solución de errores comunes

Incluso después de una configuración correcta, pueden surgir problemas con el proxy. Aquí hay un enfoque sistemático para el diagnóstico y una lista de los errores más comunes con sus soluciones.

Paso 1: Verificar la configuración actual de npm

# Mostrar todas las configuraciones de npm (incluyendo proxy)
npm config list

# Mostrar solo configuraciones de proxy
npm config get proxy
npm config get https-proxy
npm config get registry
npm config get strict-ssl

# Habilitar salida detallada para diagnóstico
npm install react --verbose
npm install react --loglevel verbose

Paso 2: Verificar la disponibilidad del registro directamente

# Verificar la disponibilidad del registro a través de curl
curl -v https://registry.npmjs.org/react/latest

# Verificar a través del proxy
curl -v --proxy http://proxy.example.com:8080 https://registry.npmjs.org/react/latest

# Verificar ping (no siempre informativo para HTTPS)
ping registry.npmjs.org

# Verificar resolución DNS
nslookup registry.npmjs.org

Errores comunes y sus soluciones

Restablecer todas las configuraciones de proxy

# Eliminar todas las configuraciones de proxy del archivo de configuración del usuario
npm config delete proxy
npm config delete https-proxy
npm config delete noproxy

# Restablecer el registro al oficial
npm config set registry https://registry.npmjs.org

# Volver a activar strict-ssl (si se desactivó)
npm config set strict-ssl true

# Verificar la configuración final
npm config list

Trabajar con pnpm y Yarn al bloquear el registro

Si utiliza administradores de paquetes alternativos, la configuración del proxy es similar, pero la sintaxis es un poco diferente:

# pnpm — utiliza el mismo .npmrc que npm
# Adicionalmente se puede configurar a través de 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) — su archivo .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+) — archivo .yarnrc.yml
# httpProxy: "http://proxy.example.com:8080"
# httpsProxy: "http://proxy.example.com:8080"
# npmRegistryServer: "https://registry.npmmirror.com"

Configuración del proxy para paquetes específicos con scope

A veces es necesario utilizar diferentes registros para diferentes paquetes: por ejemplo, tomar paquetes públicos de npmjs.org, y paquetes corporativos @company/* de un Nexus interno. Esto se configura a través de un registro específico de scope en .npmrc:

# .npmrc — diferentes registros para diferentes scopes
registry=https://registry.npmjs.org

# Paquetes corporativos @company a través de Nexus interno
@company:registry=http://nexus.company.local/repository/npm-hosted/

# Paquetes @myorg a través de Verdaccio
@myorg:registry=http://localhost:4873/

# Autenticación para un registro específico
//nexus.company.local/repository/npm-hosted/:_authToken=YOUR_TOKEN_HERE

Conclusión y recomendaciones finales

La configuración de un proxy para npm puede parecer complicada, pero siguiendo los pasos adecuados, es posible superar las restricciones de acceso y continuar con el desarrollo sin problemas. Asegúrese de documentar cualquier cambio en la configuración y de compartirlo con su equipo para mantener la coherencia y la eficiencia en el trabajo.