Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
En un clin d’œil
Objectif: Configurer Node.js applications pour utiliser le proxy de développement
Heure : 10 minutes
Prérequis :Configurer le proxy de développement, application Node.js
La façon dont vous routez les requêtes Node.js via Dev Proxy dépend de votre version de Node.js et de la bibliothèque que vous utilisez pour effectuer des requêtes HTTP. Les versions récentes de Node.js peuvent acheminer l’API native fetch et les modules http et https via un proxy défini dans les variables d’environnement. Pour les versions antérieures de Node.js et pour d’autres bibliothèques, vous configurez le proxy dans votre code ou utilisez le package global-agent pour activer la prise en charge du proxy avec des modifications de code minimales.
Quelle que soit l’approche utilisée, Node.js doit approuver le certificat racine de Dev Proxy pour effectuer des requêtes HTTPS via Dev Proxy. Pour plus d’informations, consultez Approuver le certificat du proxy de développement.
Approuver le certificat du proxy de développement
Node.js n’utilise pas le magasin de certificats du système d’exploitation par défaut. Il n’approuve donc pas le certificat racine de Dev Proxy, même une fois que vous l’avez approuvé sur votre machine. Au lieu de désactiver la validation des certificats, ajoutez le certificat racine du proxy de développement aux certificats auxquels Node.js fait confiance à l’aide de la variable d’environnement NODE_EXTRA_CA_CERTS.
NODE_EXTRA_CA_CERTS nécessite un certificat au format PEM. Pendant que Dev Proxy est en cours d’exécution, obtenez le jeton d’API à l’aide de devproxy api token, et téléchargez le certificat racine au format PEM à l’aide de Dev Proxy API :
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 vous utilisez PowerShell, exécutez :
$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"
Ensuite, faites pointer la NODE_EXTRA_CA_CERTS variable d’environnement vers le fichier téléchargé lorsque vous démarrez votre application :
NODE_EXTRA_CA_CERTS=./dev-proxy-ca.pem node index.js
Node.js lit NODE_EXTRA_CA_CERTS uniquement lorsque le processus démarre. Vous ne pouvez donc pas le définir dans votre code. Chaque installation du proxy de développement utilise son propre certificat racine. Si vous recréez le certificat, par exemple en utilisant devproxy cert remove et devproxy cert ensure, téléchargez-le à nouveau.
API fetch native de Node.js
À compter de Node.js v24.0.0 et v22.21.0, l’API native fetch peut utiliser le proxy défini dans les variables d’environnement NO_PROXY, HTTP_PROXY et HTTPS_PROXY. À compter de Node.js v24.5.0 et v22.21.0, la même chose s’applique aux modules https et http. Node.js ignore ces variables, sauf si vous activez la prise en charge du proxy en définissant la variable d’environnement NODE_USE_ENV_PROXY sur 1 ou en démarrant Node.js avec l’indicateur --use-env-proxy.
Vous n’avez pas besoin de modifier votre code pour utiliser Dev Proxy avec l’API native fetch :
(async () => {
const result = await fetch('https://jsonplaceholder.typicode.com/posts');
const jsonResult = await result.json();
console.log(JSON.stringify(jsonResult, null, 2));
})();
Lorsque vous démarrez votre application, activez la prise en charge du proxy, spécifiez Dev Proxy comme proxy et approuvez le certificat racine 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
Vous pouvez également utiliser l’indicateur --use-env-proxy au lieu de la variable d’environnement NODE_USE_ENV_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 --use-env-proxy index.js
Note
La prise en charge intégrée du proxy est en développement actif dans Node.js. Pour vérifier si votre version de Node.js la prend en charge, exécutez node --version. Si vous utilisez une version antérieure, utilisez le undici package ou le global-agent package comme décrit dans les sections suivantes.
Utiliser l’API fetch native avec des versions antérieures de Node.js
Si vous utilisez une version Node.js qui ne prend pas en charge NODE_USE_ENV_PROXY, utilisez le EnvHttpProxyAgent du package undici, qui implémente l’API native fetch dans Node.js.
EnvHttpProxyAgent lit le proxy à partir des variables d’environnement HTTPS_PROXY, NO_PROXY et HTTP_PROXY. Définissez-le comme dispatcher global au début de votre application :
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));
})();
Lorsque vous démarrez votre application, spécifiez Dev Proxy comme proxy et approuvez le certificat racine 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 est une bibliothèque populaire qui fournit un agent HTTP/HTTPS global pour Node.js. Il vous permet de spécifier le proxy à l’aide de variables d’environnement. L’avantage de l’utilisation de global-agent est que vous n’avez pas besoin de modifier la façon dont vous émettez des requêtes HTTP dans votre application pour utiliser Dev Proxy.
Voici un exemple de la façon dont vous pouvez utiliser global-agent dans une application Node.js qui utilise 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));
})();
Voici comment vous pouvez utiliser global-agent avec Node.js et le module standard 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);
});
});
Lorsque vous démarrez votre application, spécifiez le proxy à l’aide de la variable d’environnement GLOBAL_AGENT_HTTP_PROXY et faites confiance au certificat racine de Dev Proxy.
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 est une bibliothèque populaire qui fournit une fetch implémentation pour Node.js.
node-fetch ne prend pas en charge la spécification du proxy à l’aide de variables d’environnement. Au lieu de cela, vous devez créer un agent personnalisé et le transmettre à la méthode fetch.
Voici un exemple de la façon dont vous pouvez utiliser node-fetch avec Dev Proxy en définissant un agent à l’aide du package 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));
})();
Lors du démarrage de votre application, approuvez le certificat racine du proxy de développement :
NODE_EXTRA_CA_CERTS=./dev-proxy-ca.pem node index.js
Axios
Axios est une autre bibliothèque populaire pour effectuer des requêtes HTTP dans Node.js. Axios vous permet de spécifier le proxy à l’aide de variables d’environnement ou de spécifier l’agent directement dans la configuration de la demande.
Utiliser Axios et Dev Proxy avec des variables d’environnement
Lorsque vous utilisez Dev Proxy avec Axios et spécifiez le proxy à l’aide de variables d’environnement, vous n’avez pas besoin de modifier votre code. Il vous suffit de définir la https_proxy variable d’environnement et Axios l’utilise pour effectuer des requêtes.
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));
})();
Spécifiez la https_proxy variable d’environnement globalement ou lors du démarrage de votre application et faites confiance au certificat racine de Dev Proxy.
https_proxy=http://127.0.0.1:8000 NODE_EXTRA_CA_CERTS=./dev-proxy-ca.pem node axios.mjs
Got
Similaire à node-fetch, Got ne prend pas en charge la spécification du proxy à l’aide de variables d’environnement. Vous devez plutôt créer un agent personnalisé et le transmettre à la requête.
Voici un exemple de la façon dont vous pouvez utiliser Got avec le proxy de développement :
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));
})();
Lors du démarrage de votre application, approuvez le certificat racine du proxy de développement :
NODE_EXTRA_CA_CERTS=./dev-proxy-ca.pem node got.mjs
SuperAgent
SuperAgent ne prend pas en charge la spécification du proxy à l’aide de variables d’environnement. Pour utiliser Dev Proxy avec SuperAgent, vous devez installer le superagent-proxy plug-in et configurer le proxy à l’aide de la méthode 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));
})();
Lors du démarrage de votre application, approuvez le certificat racine du proxy de développement :
NODE_EXTRA_CA_CERTS=./dev-proxy-ca.pem node superagent.js
Problèmes connus
Lorsque vous utilisez Dev Proxy avec Node.js, vous pouvez rencontrer les problèmes suivants.
UNABLE_TO_VERIFY_LEAF_SIGNATURE erreur
Lorsque vous utilisez Dev Proxy avec Node.js, vous obtenez une erreur similaire à :
/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'
}
Cette erreur signifie que Node.js n’approuve pas le certificat racine du proxy de développement. Pour résoudre ce problème, téléchargez le certificat racine de Dev Proxy et définissez la NODE_EXTRA_CA_CERTS variable d’environnement sur le chemin du fichier téléchargé lors du démarrage de votre application. Pour plus d’informations, consultez Faire confiance au certificat Dev Proxy.
NODE_EXTRA_CA_CERTS=./dev-proxy-ca.pem node index.js
Avertissement
Évitez de définir NODE_TLS_REJECT_UNAUTHORIZED sur 0 afin de contourner cette erreur. Elle désactive la validation de certificat pour toutes les requêtes HTTPS effectuées par votre application.
Voir aussi
- Utiliser le proxy de développement avec des applications Node.js dans des conteneurs Docker - Configuration de Docker
- Utiliser le proxy de développement avec JavaScript Azure Functions - Azure Functions
- Glossaire - Terminologie du proxy de développement