Proxy en npm: cómo configurar npm detrás de un proxy

Publicado:

16 min de lectura

Acar Diveroli
Autor: Acar Diveroli
Ventana de terminal con tres líneas de .npmrc, la del proxy en azul, y detrás una ventana tenue con una caja de registro

Abres un proyecto en un portátil nuevo del trabajo, ejecutas npm install y durante veinte segundos no pasa nada. Luego aparece npm error code ETIMEDOUT, seguido de una pista de que quizá estás detrás de un proxy. El registro se abre sin problemas en el navegador de la misma máquina, porque el navegador usa el proxy de la empresa que le pasan Windows o macOS. npm no lee esos ajustes del sistema. Necesita los suyos.

Esta guía cubre las tres formas de darle un proxy a npm (npm config, archivos .npmrc y variables de entorno), el orden en que npm las lee, las contraseñas con caracteres especiales, cómo comprobar y quitar los ajustes, cómo dejar los hosts internos fuera del proxy y los errores habituales. Ejecutamos cada comando en Windows 11 con Node.js 24.22.2 y npm 11.19.1, contra un proxy local que anotaba cada petición y pedía contraseña, siempre con un archivo de configuración desechable.

¿Cuándo necesita npm un proxy?

npm necesita un proxy siempre que la máquina no puede llegar al registro directamente o debe llegar desde una dirección conocida. El registro (registry) es el servidor que aloja los paquetes; para la mayoría de los proyectos es https://registry.npmjs.org, pero una empresa puede tener el suyo propio.

Dos situaciones cubren casi todos los casos. Una red corporativa solo deja salir el tráfico a través de un proxy, así que una conexión directa al registro agota el tiempo de espera. O un registro privado acepta peticiones solo desde direcciones IP permitidas, y tu portátil o tu runner de CI no tiene una fija. En ambos casos hay que decirle a npm dónde está el proxy, porque no toma prestados los ajustes de proxy del sistema operativo como hace un navegador.

¿Cómo envía npm una petición a través de un proxy?

npm habla primero con el proxy y le pide que abra un túnel hacia el registro. Estos son los pasos que anotó nuestro proxy de pruebas durante npm view semver version:

  1. npm elige una dirección de proxy. Usa https-proxy si está definido y, si no, proxy. Solo cuando ambos están vacíos mira la variable de entorno HTTPS_PROXY.
  2. npm revisa la lista de exclusión. Si el host del registro coincide con una entrada de noproxy (o NO_PROXY), se salta el proxy y npm se conecta directamente.
  3. npm abre una conexión TCP con el proxy y envía CONNECT registry.npmjs.org:443. Si la dirección del proxy contiene usuario y contraseña, npm los manda en una cabecera Proxy-Authorization ya con esta primera petición. Nuestro log no mostró ninguna ida y vuelta extra: CONNECT registry.npmjs.org:443 auth user=user (ok).
  4. El proxy responde 200 Connection Established y a partir de ahí solo retransmite bytes. El handshake TLS se hace entre npm y el registro dentro del túnel, así que el proxy ve el nombre del host y el puerto, no los paquetes.
  5. npm descarga los metadatos y los tarballs y los guarda en su caché local, algo que importa más adelante cuando depures.

¿Cómo se configura el proxy de npm?

Dos comandos npm config set lo configuran para tu cuenta de usuario:

bash
npm config set proxy http://user:pass@pr.proxynet.io:8000
npm config set https-proxy http://user:pass@pr.proxynet.io:8000

npm los escribe en el archivo .npmrc de tu usuario (~/.npmrc en macOS y Linux, C:\Users\<name>\.npmrc en Windows). En nuestra máquina de prueba, el archivo contenía después exactamente estas líneas:

ini
proxy=http://user:pass@pr.proxynet.io:8000
https-proxy=http://user:pass@pr.proxynet.io:8000

Fíjate en que https-proxy también empieza por http://. El esquema describe la conexión con el proxy, no con el registro: el proxy recibe HTTP simple de npm y lleva el tráfico HTTPS dentro del túnel CONNECT. Escribe https:// solo si el propio proxy espera TLS en ese puerto.

Define las dos claves. En nuestra prueba, proxy sola bastó para el registro HTTPS, porque npm recurre a ella cuando https-proxy está vacía, pero no todas las herramientas que leen los ajustes de npm aplican la misma alternativa. npm rechaza las claves desconocidas, así que un error de tecleo como npm config set proxi … termina con npm error `proxi` is not a valid npm option.

Si la máquina tiene una IP fija, la lista de IP autorizadas de Proxynet te permite dejar las credenciales fuera de la URL: entonces http://pr.proxynet.io:8000 es todo el ajuste.

¿Qué ajustes lee npm y en qué orden?

npm combina ajustes de varias fuentes, y gana la más específica. La documentación de configuración de npm fija la prioridad así: primero las opciones de la línea de comandos, después las variables de entorno que empiezan por npm_config_, luego los archivos .npmrc y por último los valores predeterminados integrados.

FuenteEjemploAlcance
Opción de la línea de comandos--https-proxy http://…Un comando
Variable npm_config_*npm_config_https_proxyLa shell actual
.npmrc del proyecto<project>/.npmrcEse proyecto
.npmrc del usuario~/.npmrcTu cuenta
npmrc global$PREFIX/etc/npmrcTodos los usuarios de ese Node.js
npmrc integradoen la carpeta de instalación de npmEsa copia de npm

Comprobamos el orden con un archivo desechable: npm_config_proxy=http://env.example:3128 se impuso al archivo de usuario, y --proxy http://cli.example:3128 se impuso a ambos. Los nombres de las variables de entorno no distinguen mayúsculas de minúsculas, y los guiones pasan a ser guiones bajos, así que la clave https-proxy se convierte en npm_config_https_proxy.

La opción --location de npm config set elige el archivo: user es el valor predeterminado, project escribe el .npmrc junto a tu package.json y global escribe el archivo bajo el prefijo de npm. Un .npmrc de proyecto es práctico cuando solo un repositorio necesita el proxy, pero suele subirse al control de versiones, así que no metas contraseñas en él. La referencia de .npmrc documenta además la sustitución ${VARIABLE_NAME}: una línea como https-proxy=${NPM_PROXY_URL} lee la URL completa del proxy de una variable de entorno cuando npm arranca, y así el secreto no queda en el archivo. Lo probamos; con la variable sin definir, npm dejó en su sitio el texto literal ${NPM_PROXY_URL}.

¿Funcionan HTTP_PROXY y HTTPS_PROXY con npm?

HTTPS_PROXY funciona; HTTP_PROXY por sí sola no desvió el tráfico del registro en nuestra prueba. Con HTTPS_PROXY definida y ningún proxy en ningún .npmrc, cada petición al registro pasó por nuestro proxy. Con solo HTTP_PROXY, npm view se conectó directamente y el log del proxy quedó vacío, aunque la propia descripción de https-proxy en npm menciona HTTP_PROXY como alternativa. El código de npm 11.19.1 solo lee HTTPS_PROXY para las direcciones https://, y el registro público funciona sobre HTTPS.

El patrón seguro para una shell, un contenedor o un trabajo de CI es definir las dos, más las exclusiones:

bash
export HTTPS_PROXY="http://user:pass@pr.proxynet.io:8000"
export HTTP_PROXY="$HTTPS_PROXY"
export NO_PROXY="localhost,127.0.0.1,.internal.example"

En Windows PowerShell, las mismas líneas son $env:HTTPS_PROXY = "http://user:pass@pr.proxynet.io:8000" y así sucesivamente. Una trampa: npm config get https-proxy imprime null aunque HTTPS_PROXY esté definida, porque npm aplica la variable solo en el momento de enviar una petición. No interpretes ese null como «sin proxy».

¿Cómo se ponen usuario y contraseña en la URL del proxy?

Escríbelos delante del host como user:password@ y aplica codificación porcentual a cada carácter que tenga un significado en una URL. La codificación porcentual sustituye un carácter por % y su código hexadecimal. Los caracteres que rompen una URL de proxy son los delimitadores que enumera la RFC 3986, sección 2.2: :, /, ?, #, [, ] y @. Un espacio y el propio % también hay que codificarlos.

CarácterCodificado
@%40
:%3A
#%23
/%2F
%%25
espacio%20

Nuestro proxy de prueba aceptaba la contraseña p@ss:w#rd. Escrita tal cual, como http://user:p@ss:w#rd@127.0.0.1:18080, npm ni siquiera llegó al proxy: Node.js avisó de que la URL no era válida y npm se detuvo con getaddrinfo ENOTFOUND ss. Había tomado el texto tras la primera @ como nombre del host. Codificada como http://user:p%40ss%3Aw%23rd@127.0.0.1:18080, el mismo comando devolvió la versión del paquete y el proxy anotó un inicio de sesión correcto. Si un error de DNS nombra un host que nunca escribiste, mira primero la contraseña.

¿Cómo se comprueban y se quitan los ajustes de proxy de npm?

npm config list muestra cada ajuste que difiere del predeterminado y el archivo del que procede. En nuestra ejecución, la salida empezaba con una línea que nombraba la fuente, ; "user" config from …\test.npmrc, seguida de proxy = "http://user:***@pr.proxynet.io:8000". npm enmascara la contraseña en esta vista, así que puedes pegar la salida en una incidencia de soporte sin riesgo.

npm config get proxy se niega a imprimir un valor que contenga una contraseña: The proxy option is protected, and cannot be retrieved in this way. Sin credenciales en la URL, imprime la dirección tal como está guardada; npm config edit abre el propio archivo.

Para quitar el proxy, borra las dos claves:

bash
npm config delete proxy
npm config delete https-proxy

Cada delete elimina una línea de un archivo; en nuestra prueba, la línea https-proxy siguió ahí hasta que la borramos por separado. Añade --location=project o --location=global para los otros archivos, y revisa HTTPS_PROXY y npm_config_https_proxy en tu shell, porque una variable olvidada sigue desviando el tráfico aunque el archivo esté limpio. Para saltarte el proxy en un solo comando sin tocar el archivo, pasa el host del registro como exclusión: --noproxy registry.npmjs.org.

¿Cómo se dejan algunos hosts fuera del proxy?

Ponlos en noproxy, separados por comas. npm compara el nombre del host segmento a segmento desde la derecha, así que .internal.example coincide con registry.internal.example y con cualquier otro nombre bajo ese dominio.

bash
npm config set noproxy "localhost,127.0.0.1,.internal.example"

Cuando añadimos el host del registro público a noproxy (y, en una segunda ejecución, a NO_PROXY), npm se conectó directamente y el proxy no anotó nada. La clave noproxy toma por defecto el valor de NO_PROXY, así que mantén una sola lista, no dos distintas.

Errores comunes del proxy de npm y cómo resolverlos

Estos son los mensajes que npm 11 mostró en nuestras pruebas, más dos que no reprodujimos:

  • npm error code E407 con 407 Proxy Authentication Required. El proxy quiere un inicio de sesión y no recibió ninguno, o recibió uno incorrecto. Una contraseña ausente y una contraseña errónea produjeron el mismo texto. Revisa el usuario, la codificación de los caracteres especiales y, si dependes de ella, si tu IP está en la lista de IP autorizadas.
  • getaddrinfo ENOTFOUND seguido de un nombre de host extraño. La URL del proxy se interpretó mal, casi siempre por una @ o un # sin codificar en la contraseña. Si el host nombrado es el propio proxy, revisa cómo está escrito y tu DNS.
  • connect ECONNREFUSED <proxy-ip>:<port>. Nada escucha en ese puerto: un número de puerto equivocado, o el proxy está caído.
  • connect ETIMEDOUT <ip>:<port>. Los paquetes no llegan a ninguna parte; nuestra dirección de prueba inalcanzable falló tras unos 22 segundos. Si hay un proxy definido, su dirección está mal; si no hay ninguno, probablemente la red solo deja salir el tráfico a través de un proxy.
  • ECONNRESET. La conexión se abrió y luego se cortó, normalmente por un proxy que cierra las descargas largas o por un antivirus que inspecciona el tráfico. --loglevel verbose muestra qué petición falló.
  • UNABLE_TO_GET_ISSUER_CERT_LOCALLY o SELF_SIGNED_CERT_IN_CHAIN. Un proxy de empresa inspecciona el HTTPS y lo vuelve a firmar con su propio certificado raíz, en el que Node.js no confía. Guarda ese certificado raíz en un archivo y apunta a él el ajuste cafile de npm o la variable NODE_EXTRA_CA_CERTS; la diferencia entre ambos, y cómo encontrar el certificado correcto, la explicamos en nuestra guía sobre el error del certificado del emisor local.

strict-ssl=false hace desaparecer el último error desactivando la comprobación de certificados para el registro. Úsalo como mucho durante un minuto de depuración, nunca como solución: con él, cualquiera en el camino de red puede entregarle a npm un paquete modificado.

Otra trampa nos hizo perder tiempo. Con la caché llena, npm view imprimió una versión aunque nada escuchaba en el puerto del proxy; npm respondió desde su caché. Solo con la caché vacía apareció ECONNREFUSED. Si un cambio de proxy parece funcionar, prueba con un paquete que nunca hayas instalado, o con --prefer-online y una carpeta de caché nueva mediante --cache.

¿Usan Yarn y pnpm los mismos ajustes?

pnpm lee las mismas claves de .npmrc, mientras que Yarn 2 y posteriores usan su propio archivo. Los ajustes de red de pnpm describen https-proxy, http-proxy y noproxy, con la clave antigua proxy de npm como alternativa para ambas y, después, las variables HTTPS_PROXY, HTTP_PROXY y NO_PROXY. pnpm solo lee de .npmrc los ajustes de autenticación, registro, TLS, proxy y local-address, así que una configuración de proxy de npm existente suele funcionar sin cambios.

Yarn 2 y posteriores (Yarn Berry) guardan sus ajustes en .yarnrc.yml, con las claves httpProxy y httpsProxy, que se definen por ejemplo con yarn config set httpsProxy http://user:pass@pr.proxynet.io:8000. Su opción de certificado es httpsCaFilePath, y enableStrictSsl vale true por defecto, según la referencia de configuración de Yarn.

¿Llega el proxy a los scripts de instalación y al propio Node.js?

Solo en parte. npm pasa sus ajustes a los scripts de los paquetes como variables de entorno: en nuestra prueba, un script lanzado con npm run vio npm_config_https_proxy y npm_config_noproxy. Que un script las use depende de su autor, así que un paquete que descarga un binario durante la instalación puede fallar igualmente detrás de un proxy. Cuando ocurre, la documentación del propio paquete suele indicar la variable que lee.

Tu propio código Node.js es otro asunto. El fetch integrado de Node.js ignora HTTPS_PROXY salvo que el proceso arranque con NODE_USE_ENV_PROXY=1 o con la opción --use-env-proxy, que admiten las versiones actuales de Node.js; las opciones de cada biblioteca están en Cómo usar un proxy en Node.js.

Las dependencias que se instalan directamente desde un repositorio Git (una dirección git+https:// en package.json) las descarga Git, no el código de red de npm. Git tiene sus propios ajustes de proxy, descritos en Configuración de proxy en Git.

¿Cuándo ayuda una IP de proxy fija?

Una IP de salida fija ayuda cuando es el registro, y no tu red, quien decide quién puede conectarse. Los registros autoalojados y los espejos de paquetes suelen estar protegidos por una regla de firewall que permite una lista corta de direcciones de origen. Los agentes de compilación en la nube reciben una dirección nueva en cada ejecución, así que la regla nunca coincide. Si npm pasa por un proxy con una dirección dedicada que no cambia, el firewall solo necesita una entrada.

Los Proxies de centro de datos mantienen la misma IP dedicada mientras la conserves, algo que encaja con los servidores de compilación.

Los Proxies ISP hacen lo mismo con una dirección registrada a nombre de un proveedor de internet. Ambos se venden por IP y vienen por defecto con una restricción de sitios de destino; comprueba que el host de tu registro esté cubierto o añade la opción «Acceso a todos los sitios web». Detrás de un proxy corporativo nada de esto aplica: usa la dirección que te dé tu equipo de TI.

Guía de decisión

NecesidadAjuste
Cada instalación en tu máquinanpm config set proxy y https-proxy
Solo un proyecto--location=project, sin contraseña dentro
Trabajo de CI o contenedorHTTPS_PROXY más HTTP_PROXY y NO_PROXY
Un solo comandoOpción --https-proxy
Acceso directo al registro internonoproxy con su dominio
Contraseña con @ o #Codificación porcentual
Contraseña fuera de los archivos${VAR} en .npmrc o lista de IP autorizadas
Proxy de empresa con inspección TLScafile o NODE_EXTRA_CA_CERTS
Registro que solo admite IP permitidasProxy con IP dedicada

Preguntas frecuentes

¿Cómo configuro un proxy en npm?

Ejecuta npm config set proxy http://host:port y npm config set https-proxy http://host:port, y añade user:pass@ delante del host si el proxy pide inicio de sesión. Los ajustes van a tu .npmrc de usuario y se aplican desde ese momento a cada comando de npm.

¿Cómo configuro un proxy de npm con usuario y contraseña?

Ponlos en la URL como http://user:password@host:port y codifica los caracteres especiales de ambas partes: @ pasa a %40, : a %3A y # a %23. Una @ sin codificar hace que npm lea el resto de la contraseña como nombre del host y falle con ENOTFOUND.

¿Cómo quito el proxy de npm?

Ejecuta npm config delete proxy y npm config delete https-proxy, y luego comprueba con npm config list. Si el tráfico sigue pasando por un proxy, busca HTTPS_PROXY o npm_config_https_proxy en tu entorno y un .npmrc de proyecto o global.

¿Dónde se guarda la configuración de proxy de npm?

En un archivo .npmrc: por usuario en tu carpeta personal de forma predeterminada, por proyecto junto a package.json o de forma global bajo el prefijo de npm. npm config list imprime la ruta de cada archivo leído encima de los ajustes que vienen de él.

¿Usa npm el proxy del sistema en Windows?

No. npm solo lee sus propios ajustes y las variables de entorno, no el proxy configurado en los ajustes de red de Windows ni en Opciones de Internet. Define la misma dirección con npm config set o con HTTPS_PROXY.

¿Puede npm usar un proxy SOCKS5?

La capa de red de npm incluye un cliente SOCKS y acepta direcciones como socks5://host:port en los ajustes de proxy, según muestra el código fuente de npm 11; no lo probamos contra un servidor SOCKS real. Si falla en tu versión, usa el endpoint HTTP del proveedor, que es la vía que usaron todas las pruebas de esta guía.

En resumen

Dale un proxy a npm con npm config set proxy y npm config set https-proxy, o con HTTPS_PROXY en shells y CI; HTTP_PROXY sola no desvió el tráfico del registro en nuestra prueba. Los ajustes de la línea de comandos se imponen a las variables npm_config_*, y estas a los archivos .npmrc de proyecto, de usuario y global. Codifica los caracteres especiales de la contraseña, mantén los hosts internos en noproxy, comprueba con npm config list y quita las dos claves con npm config delete. Los errores de certificado detrás de un proxy de empresa necesitan el certificado raíz de la empresa, no strict-ssl=false. Los endpoints de proxy que funcionan con todos estos ajustes están en la página de proxies de Proxynet.