Configuration de proxy en Node.js : axios, got, fetch et undici (Guide 2026)

Chaque client HTTP de Node.js gère les proxys différemment, et la moitié d'entre eux ne gèrent pas du tout l'authentification de proxy sans un paquet auxiliaire. axios ignore silencieusement sa propre option proxy pour les cibles HTTPS dans certaines versions, le fetch natif n'a aucune option de proxy, et les messages d'erreur — ECONNRESET, 407 ou simplement un blocage — ne vous apprennent rien.

Voici la référence complète et fonctionnelle pour router axios, got, node-fetch, fetch natif (undici) et superagent à travers des proxys résidentiels authentifiés. C'est le complément Node de nos guides Python (requests/httpx/aiohttp, Scrapy). Tous les exemples utilisent le format de marqueur standard — remplacez par vos véritables identifiants :

socks5h://USERNAME:[email protected]:913

La seule règle qui évite la plupart des bugs

N'utilisez pas les options proxy intégrées. Utilisez un agent de proxy. Les clients HTTP de Node délèguent la gestion de la connexion à un objet « agent », et les paquets d'agents (https-proxy-agent, socks-proxy-agent) implémentent correctement le tunneling CONNECT et l'authentification. Les options intégrées ne le font souvent pas — la configuration proxy d'axios en est l'exemple le plus notoire.

npm install socks-proxy-agent https-proxy-agent

axios

const axios = require("axios");
const { SocksProxyAgent } = require("socks-proxy-agent");

const agent = new SocksProxyAgent(
  "socks5h://USERNAME:[email protected]:913"
);

const res = await axios.get("https://api.ipify.org?format=json", {
  httpAgent: agent,    // for http:// targets
  httpsAgent: agent,   // for https:// targets
  proxy: false,        // IMPORTANT: disable axios's own proxy handling
});
console.log(res.data); // -> the proxy's exit IP

Deux choses que les gens oublient : vous devez définir à la fois httpAgent et httpsAgent (axios choisit selon le schéma de la cible), et vous devez définir proxy: false pour qu'axios n'essaie pas non plus d'appliquer les variables d'environnement HTTP_PROXY par-dessus votre agent.

got

const got = require("got");
const { SocksProxyAgent } = require("socks-proxy-agent");

const agent = new SocksProxyAgent(
  "socks5h://USERNAME:[email protected]:913"
);

const body = await got("https://api.ipify.org?format=json", {
  agent: { http: agent, https: agent },
}).json();

Si vous faites du scraping de cibles protégées avec got, regardez plutôt got-scraping — la même API, plus une génération d'en-têtes proches de celles d'un navigateur et une imitation de l'empreinte HTTP/2 (pourquoi ça compte : JA3/JA4 expliqué).

fetch natif / undici (Node 18+)

Le fetch intégré de Node provient d'undici, ignore les variables d'environnement de proxy et n'a pas d'option agent. La méthode undici est un dispatcher :

const { ProxyAgent } = require("undici");

// undici's ProxyAgent speaks HTTP CONNECT (use your HTTP proxy port)
const dispatcher = new ProxyAgent({
  uri: "http://us.jibaoproxy.com:1000",
  token: "Basic " + Buffer.from("USERNAME:PASSWORD").toString("base64"),
});

const res = await fetch("https://api.ipify.org?format=json", { dispatcher });
console.log(await res.json());

Note : le ProxyAgent d'undici est uniquement pour les proxys HTTP. Pour SOCKS5 avec fetch natif, placez devant un redirecteur local ou utilisez un client qui accepte les agents socks (axios/got ci-dessus).

node-fetch (v2/v3)

const fetch = require("node-fetch");
const { SocksProxyAgent } = require("socks-proxy-agent");

const agent = new SocksProxyAgent(
  "socks5h://USERNAME:[email protected]:913"
);

const res = await fetch("https://api.ipify.org?format=json", { agent });

Rotation : nouvelle identité par requête vs. sessions sticky

Avec une passerelle résidentielle rotative, vous ne gérez pas de listes d'IP — la passerelle vous fournit une sortie fraîche par connexion, ou conserve une sortie par identifiant de session. En Node, cela se traduit proprement par un agent par identité :

// Sticky: same session id -> same exit IP across requests
function identityAgent(sessionId) {
  return new SocksProxyAgent(
    `socks5h://USERNAME-session-${sessionId}:[email protected]:913`
  );
}

// Account A keeps IP A, account B keeps IP B - cookies and IP move together
const agentA = identityAgent("acct_a");
const agentB = identityAgent("acct_b");

Réutilisez l'agent pour le pooling de connexions au sein d'une identité ; ne partagez jamais un même agent entre plusieurs identités. Quand faut-il faire tourner les IP plutôt que les fixer (sticky) est un sujet à part entière — voir sessions sticky vs. rotatives.

Tableau de dépannage

Symptôme	Cause	Solution
407 Proxy Authentication Required	Les identifiants n'atteignent pas le proxy	Mettez user:pass dans l'URL de l'agent, pas dans la configuration du client
axios fonctionne en http://, échoue en https://	Seul httpAgent est défini	Définissez aussi httpsAgent et proxy: false
ECONNRESET immédiatement	Mauvais port / mauvais protocole (port HTTP avec un agent SOCKS)	Faites correspondre le type d'agent au port
Fuites DNS / les noms d'hôte internes échouent	socks5:// résout le DNS localement	Utilisez socks5h:// — le h envoie les noms d'hôte à travers le proxy
fetch natif ignore HTTP_PROXY	undici ne lit pas les variables d'environnement	Passez un dispatcher explicitement
Fonctionne en local, 403 sur le site cible	Ce n'est pas un bug du proxy — c'est l'empreinte TLS	got-scraping ou un vrai navigateur ; voir le guide TLS

Résumé

• Utilisez toujours les paquets d'agents (socks-proxy-agent / https-proxy-agent) ; ne faites jamais confiance aux options de proxy intégrées.
• axios : les deux agents + proxy: false. got : agent: {http, https}. fetch natif : dispatcher ProxyAgent d'undici.
• Utilisez socks5h:// pour que le DNS se résolve à travers le proxy — aucune fuite.
• Un agent par identité : les identifiants de session sticky font bouger les cookies et l'IP de sortie ensemble.
• Toujours bloqué avec un proxy qui fonctionne ? C'est de l'empreinte digitale, pas le proxy — passez à got-scraping ou à un navigateur.