Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
De un vistazo
Objetivo: Configurar aplicaciones de Node.js para utilizar el proxy de desarrollo
Hora: 10 minutos
Requisitos previos:Configuración del Proxy de Desarrollo, Aplicación Node.js
La manera de enrutar las solicitudes Node.js a través del proxy de desarrollo depende de la versión de Node.js y de la biblioteca que use para realizar solicitudes HTTP. Las versiones recientes de Node.js pueden enrutar la API nativa fetch y los módulos http y https a través de un proxy definido en variables de entorno. Para versiones anteriores de Node.js y para otras bibliotecas, configure el proxy en el código o use el paquete global-agent para habilitar la compatibilidad con el proxy con cambios mínimos en el código.
Cualquier enfoque que use, Node.js debe confiar en el certificado raíz de proxy de desarrollo para realizar solicitudes HTTPS a través del proxy de desarrollo. Para obtener más información, consulte Confiar en el certificado de Dev Proxy.
Confiar en el certificado del proxy de desarrollo
Node.js no usa el almacén de certificados del sistema operativo de forma predeterminada, por lo que no confía en el certificado raíz del proxy de desarrollo incluso después de confiar en él en el equipo. En lugar de deshabilitar la validación de certificados, agregue el certificado raíz del proxy de desarrollo a los certificados en los que confía Node.js mediante la variable de entorno NODE_EXTRA_CA_CERTS.
NODE_EXTRA_CA_CERTS requiere un certificado en formato PEM. Mientras se ejecuta Dev Proxy, obtenga el token de API mediante devproxy api tokeny descargue el certificado raíz en el formato PEM mediante la API de Dev Proxy:
TOKEN=$(devproxy api token)
curl -H "Authorization: Bearer $TOKEN" -o dev-proxy-ca.pem "http://127.0.0.1:8897/proxy/rootCertificate?format=crt"
Si usa PowerShell, ejecute lo siguiente:
$token = devproxy api token
Invoke-WebRequest -Headers @{ Authorization = "Bearer $token" } -OutFile dev-proxy-ca.pem -Uri "http://127.0.0.1:8897/proxy/rootCertificate?format=crt"
A continuación, apunte la NODE_EXTRA_CA_CERTS variable de entorno al archivo descargado al iniciar la aplicación:
NODE_EXTRA_CA_CERTS=./dev-proxy-ca.pem node index.js
Node.js solo lee NODE_EXTRA_CA_CERTS cuando se inicia el proceso, por lo que no se puede establecer desde el código. Cada instalación de Dev Proxy usa su propio certificado raíz. Si vuelve a crear el certificado, por ejemplo, con devproxy cert remove y devproxy cert ensure, descárguelo de nuevo.
API nativa de fetch de Node.js
A partir de Node.js v24.0.0 y v22.21.0, la API nativa fetch puede usar el proxy definido en las HTTP_PROXYvariables de entorno , HTTPS_PROXYy NO_PROXY . A partir de Node.js v24.5.0 y v22.21.0, se aplica lo mismo a los módulos http y https. Node.js omite estas variables a menos que habilite la compatibilidad con proxy estableciendo la NODE_USE_ENV_PROXY variable de entorno en 1 o iniciando Node.js con la --use-env-proxy marca .
No es necesario cambiar el código para usar dev Proxy con la API nativa fetch :
(async () => {
const result = await fetch('https://jsonplaceholder.typicode.com/posts');
const jsonResult = await result.json();
console.log(JSON.stringify(jsonResult, null, 2));
})();
Al iniciar la aplicación, habilite la compatibilidad con proxy, especifique Dev Proxy como proxy y confíe en el certificado raíz de Dev Proxy:
NODE_USE_ENV_PROXY=1 HTTPS_PROXY=http://127.0.0.1:8000 HTTP_PROXY=http://127.0.0.1:8000 NODE_EXTRA_CA_CERTS=./dev-proxy-ca.pem node index.js
Como alternativa, use el --use-env-proxy indicador en lugar de la NODE_USE_ENV_PROXY variable de entorno:
HTTPS_PROXY=http://127.0.0.1:8000 HTTP_PROXY=http://127.0.0.1:8000 NODE_EXTRA_CA_CERTS=./dev-proxy-ca.pem node --use-env-proxy index.js
Note
La compatibilidad integrada con proxy está en desarrollo activo en Node.js. Para comprobar si la versión de Node.js la admite, ejecute node --version. Si usa una versión anterior, use el undici paquete o el global-agent paquete como se describe en las secciones siguientes.
Usa la API fetch nativa con versiones anteriores de Node.js
Si usa una versión de Node.js que no admite NODE_USE_ENV_PROXY, use el EnvHttpProxyAgent del paquete undici, que implementa la API nativa fetch en Node.js.
EnvHttpProxyAgent obtiene la configuración del proxy de las variables de entorno HTTP_PROXY, HTTPS_PROXY y NO_PROXY. Establézcalo como distribuidor global al principio de la aplicación:
import { EnvHttpProxyAgent, setGlobalDispatcher } from 'undici';
setGlobalDispatcher(new EnvHttpProxyAgent());
(async () => {
const result = await fetch('https://jsonplaceholder.typicode.com/posts');
const jsonResult = await result.json();
console.log(JSON.stringify(jsonResult, null, 2));
})();
Al iniciar la aplicación, especifique Dev Proxy como proxy y confíe en el certificado raíz de Dev Proxy:
HTTPS_PROXY=http://127.0.0.1:8000 HTTP_PROXY=http://127.0.0.1:8000 NODE_EXTRA_CA_CERTS=./dev-proxy-ca.pem node index.mjs
global-agent
global-agent es una biblioteca popular que proporciona un agente HTTP/HTTPS global para Node.js. Permite especificar el proxy mediante variables de entorno. La ventaja de usar global-agent es que no es necesario cambiar cómo realiza solicitudes HTTP en la aplicación para usar el proxy de desarrollo.
Este es un ejemplo de cómo puede usar global-agent en una aplicación de Node.js que usa node-fetch:
import fetch from 'node-fetch';
import { bootstrap } from 'global-agent';
bootstrap();
(async () => {
const result = await fetch('https://jsonplaceholder.typicode.com/posts');
const jsonResult = await result.json();
console.log(JSON.stringify(jsonResult, null, 2));
})();
Aquí se muestra cómo puede usar global-agent con Node.js y el módulo estándar https :
const https = require('https');
const globalAgent = require('global-agent');
globalAgent.bootstrap();
https.get('https://jsonplaceholder.typicode.com/posts', (resp) => {
let data = '';
resp.on('data', (d) => {
data += d;
});
resp.on('end', () => {
console.log(JSON.parse(data));
});
resp.on('error', (err) => {
console.error(err);
});
});
Al iniciar la aplicación, especifique el proxy mediante la GLOBAL_AGENT_HTTP_PROXY variable de entorno y confíe en el certificado raíz del proxy de desarrollo.
NODE_EXTRA_CA_CERTS=./dev-proxy-ca.pem GLOBAL_AGENT_HTTP_PROXY=http://127.0.0.1:8000 node global-node-fetch.mjs
node-fetch
node-fetch es una biblioteca popular que proporciona una fetch implementación para Node.js.
node-fetch no admite la especificación del proxy mediante variables de entorno. En su lugar, debe crear un agente personalizado y pasarlo al fetch método .
Este es un ejemplo de cómo puede usar node-fetch con Dev Proxy mediante la definición de un agente mediante el paquete https-proxy-agent.
const fetch = require('node-fetch');
const { HttpsProxyAgent } = require('https-proxy-agent');
(async () => {
// Create a custom agent pointing to Dev Proxy
const agent = new HttpsProxyAgent('http://127.0.0.1:8000');
// Pass the agent to the fetch method
const result = await fetch('https://jsonplaceholder.typicode.com/posts', { agent });
const jsonResult = await result.json();
console.log(JSON.stringify(jsonResult, null, 2));
})();
Al iniciar la aplicación, confíe en el certificado raíz del proxy de desarrollo:
NODE_EXTRA_CA_CERTS=./dev-proxy-ca.pem node index.js
Axios
Axios es otra biblioteca popular para realizar solicitudes HTTP en Node.js. Axios permite especificar el proxy mediante variables de entorno o especificar el agente directamente en la configuración de la solicitud.
Usa Axios y Dev Proxy con variables de entorno
Cuando se usa Dev Proxy con Axios y se especifica el proxy mediante variables de entorno, no es necesario cambiar el código. Lo único que debe hacer es establecer la variable de entorno https_proxy y Axios la usa para realizar solicitudes.
import axios from 'axios';
(async () => {
const result = await axios.get('https://jsonplaceholder.typicode.com/posts');
const response = result.data;
console.log(JSON.stringify(response, null, 2));
})();
Especifique la https_proxy variable de entorno globalmente o al iniciar la aplicación y confíe en el certificado raíz del proxy de desarrollo.
https_proxy=http://127.0.0.1:8000 NODE_EXTRA_CA_CERTS=./dev-proxy-ca.pem node axios.mjs
Tiene
De forma similar a node-fetch, Got no admite la especificación del proxy mediante variables de entorno. En su lugar, debe crear un agente personalizado y pasarlo a la solicitud.
Este es un ejemplo de cómo puede usar Got con Dev Proxy:
import got from 'got';
import { HttpsProxyAgent } from 'https-proxy-agent';
(async () => {
// Create a custom agent pointing to Dev Proxy
const agent = new HttpsProxyAgent('http://127.0.0.1:8000');
const result = await got('https://jsonplaceholder.typicode.com/posts', {
// Pass the agent to the request
agent: {
https: agent
}
}).json();
console.log(JSON.stringify(result, null, 2));
})();
Al iniciar la aplicación, confíe en el certificado raíz del proxy de desarrollo:
NODE_EXTRA_CA_CERTS=./dev-proxy-ca.pem node got.mjs
SuperAgent
SuperAgent no admite la especificación del proxy mediante variables de entorno. Para usar Dev Proxy con SuperAgent, debe instalar el complemento superagent-proxy y configurar el proxy mediante el método proxy.
const superagent = require('superagent');
require('superagent-proxy')(superagent);
(async () => {
const result = await superagent
.get('https://jsonplaceholder.typicode.com/posts')
.proxy('http://127.0.0.1:8000');
console.log(JSON.stringify(result.body, null, 2));
})();
Al iniciar la aplicación, confíe en el certificado raíz del proxy de desarrollo:
NODE_EXTRA_CA_CERTS=./dev-proxy-ca.pem node superagent.js
Problemas conocidos
Al usar Dev Proxy con Node.js, es posible que encuentre los siguientes problemas.
Error UNABLE_TO_VERIFY_LEAF_SIGNATURE
Al usar Dev Proxy con Node.js, obtendrá un error similar al siguiente:
/Users/user/my-app/node_modules/node-fetch/lib/index.js:1501
reject(new FetchError(`request to ${request.url} failed, reason: ${err.message}`, 'system', err));
^
FetchError: request to https://jsonplaceholder.typicode.com/posts failed, reason: unable to verify the first certificate
at ClientRequest.<anonymous> (/Users/user/my-app/node_modules/node-fetch/lib/index.js:1501:11)
at ClientRequest.emit (node:events:518:28)
at TLSSocket.socketErrorListener (node:_http_client:495:9)
at TLSSocket.emit (node:events:518:28)
at emitErrorNT (node:internal/streams/destroy:169:8)
at emitErrorCloseNT (node:internal/streams/destroy:128:3)
at process.processTicksAndRejections (node:internal/process/task_queues:82:21) {
type: 'system',
errno: 'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
code: 'UNABLE_TO_VERIFY_LEAF_SIGNATURE'
}
Este error significa que Node.js no confía en el certificado raíz del proxy de desarrollo. Para corregir este problema, descargue el certificado raíz de proxy de desarrollo y establezca la variable de entorno NODE_EXTRA_CA_CERTS en la ruta de acceso del archivo descargado al iniciar la aplicación. Para obtener más información, consulte Confiar en el certificado de Dev Proxy.
NODE_EXTRA_CA_CERTS=./dev-proxy-ca.pem node index.js
Warning
Evite establecer NODE_TLS_REJECT_UNAUTHORIZED en 0 para evitar este error. Deshabilita la validación de certificados para todas las solicitudes HTTPS que realiza la aplicación.
Consulte también
- Uso del proxy de desarrollo con aplicaciones de Node.js en contenedores de Docker : configuración de Docker
- Uso de proxy de desarrollo con JavaScript Azure Functions: Azure Functions
- Glosario : terminología del proxy de desarrollo