راه‌اندازی پروکسی در Node.js: axios، got، fetch و undici (راهنمای ۲۰۲۶)

هر کلاینت HTTP در Node.js پروکسی‌ها را متفاوت مدیریت می‌کند، و نیمی از آن‌ها بدون یک پکیج کمکی اصلاً احراز هویت پروکسی را مدیریت نمی‌کنند. axios در برخی نسخه‌ها آپشن proxy خودش را برای هدف‌های HTTPS بی‌سروصدا نادیده می‌گیرد، fetch بومی اصلاً هیچ آپشن پروکسی‌ای ندارد، و پیام‌های خطا — ECONNRESET، 407، یا فقط یک گیر کردن — هیچ چیزی به شما نمی‌گویند.

این مرجع کامل و کارا برای عبور دادن axios، got، node-fetch، fetch بومی (undici)، و superagent از طریق پروکسی‌های مسکونی احراز هویت‌دار است. این همراهِ Node برای راهنماهای پایتون ما است (requests/httpx/aiohttp، Scrapy). همه مثال‌ها از فرمت placeholder استاندارد استفاده می‌کنند — اطلاعات احراز هویت واقعی خودتان را جایگزین کنید:

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

تنها قانونی که جلوی بیشتر باگ‌ها را می‌گیرد

از آپشن‌های proxy توکار استفاده نکنید. از یک proxy agent استفاده کنید. کلاینت‌های HTTP در Node مدیریت اتصال را به یک شیء «agent» واگذار می‌کنند، و پکیج‌های agent (https-proxy-agent، socks-proxy-agent) تونل‌سازی CONNECT و احراز هویت را درست پیاده‌سازی می‌کنند. آپشن‌های توکار اغلب این کار را نمی‌کنند — کانفیگ proxy مربوط به axios بدنام‌ترین نمونه است.

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,    // برای هدف‌های http://
  httpsAgent: agent,   // برای هدف‌های https://
  proxy: false,        // مهم: مدیریت پروکسی خود axios را غیرفعال کنید
});
console.log(res.data); // -> IP خروجی پروکسی

دو چیز که مردم از قلم می‌اندازند: باید هم httpAgent و هم httpsAgent را ست کنید (axios بر اساس scheme هدف انتخاب می‌کند)، و باید proxy: false ست کنید تا axios علاوه بر agent شما، متغیرهای محیطی HTTP_PROXY را هم اعمال نکند.

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();

اگر با got هدف‌های محافظت‌شده را اسکرپ می‌کنید، به‌جایش به got-scraping نگاه کنید — همان API، به‌علاوه تولید هدر مرورگرمانند و تقلید فینگرپرینت HTTP/2 (چرا این مهم است: توضیح JA3/JA4).

fetch بومی / undici (Node 18+)

fetch توکار Node از undici می‌آید، متغیرهای محیطی پروکسی را نادیده می‌گیرد، و آپشن agent ندارد. راه undici استفاده از یک dispatcher است:

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

// ProxyAgent مربوط به undici با HTTP CONNECT حرف می‌زند (از پورت HTTP پروکسی استفاده کنید)
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());

توجه: ProxyAgent مربوط به undici فقط HTTP-proxy است. برای SOCKS5 با fetch بومی، یا جلویش یک forwarder محلی بگذارید یا از کلاینتی استفاده کنید که socks agent می‌پذیرد (axios/got بالا).

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 });

چرخش: هویت جدید به‌ازای هر درخواست در برابر sticky session

با یک گیت‌وی مسکونی چرخشی، شما فهرست IP مدیریت نمی‌کنید — گیت‌وی به‌ازای هر اتصال یک خروجی تازه به شما می‌دهد، یا یک خروجی به‌ازای هر session id نگه می‌دارد. در Node این به‌خوبی به یک agent به‌ازای هر هویت نگاشت می‌شود:

// Sticky: همان session id -> همان IP خروجی در طول درخواست‌ها
function identityAgent(sessionId) {
  return new SocksProxyAgent(
    `socks5h://USERNAME-session-${sessionId}:[email protected]:913`
  );
}

// حساب A همان IP A را نگه می‌دارد، حساب B همان IP B - کوکی‌ها و IP با هم حرکت می‌کنند
const agentA = identityAgent("acct_a");
const agentB = identityAgent("acct_b");

agent را برای connection pooling درون یک هویت دوباره استفاده کنید؛ هرگز یک agent را بین هویت‌ها به اشتراک نگذارید. اینکه کِی چرخش دهید و کِی sticky بمانید موضوع خودش است — sticky در برابر rotating session را ببینید.

جدول عیب‌یابی

نشانه	علت	راه‌حل
407 Proxy Authentication Required	اطلاعات احراز هویت به پروکسی نمی‌رسد	user:pass را در URL مربوط به agent بگذارید، نه در کانفیگ کلاینت
axios روی http:// کار می‌کند، روی https:// شکست می‌خورد	فقط httpAgent ست شده	httpsAgent را هم ست کنید، و proxy: false
ECONNRESET بلافاصله	پورت غلط / پروتکل غلط (پورت HTTP با socks agent)	نوع agent را با پورت هماهنگ کنید
نشت DNS / hostname های داخلی شکست می‌خورند	socks5:// DNS را محلی resolve می‌کند	از socks5h:// استفاده کنید — حرف h hostname ها را از طریق پروکسی می‌فرستد
fetch بومی HTTP_PROXY را نادیده می‌گیرد	undici متغیرهای محیطی را نمی‌خواند	یک dispatcher را صراحتاً پاس دهید
محلی کار می‌کند، روی سایت هدف ۴۰۳	باگ پروکسی نیست — فینگرپرینت TLS	got-scraping یا یک مرورگر واقعی؛ راهنمای TLS را ببینید

جمع‌بندی

• همیشه از پکیج‌های agent (socks-proxy-agent / https-proxy-agent) استفاده کنید؛ هرگز به آپشن‌های پروکسی توکار اعتماد نکنید.
• axios: هر دو agent + proxy: false. got: agent: {http, https}. fetch بومی: dispatcher مربوط به ProxyAgent در undici.
• از socks5h:// استفاده کنید تا DNS از طریق پروکسی resolve شود — بدون نشت.
• یک agent به‌ازای هر هویت: session id های sticky کوکی‌ها و IP خروجی را با هم نگه می‌دارند.
• با یک پروکسی سالم هنوز بلاک می‌شوید؟ آن فینگرپرینتینگ است، نه پروکسی — به got-scraping یا یک مرورگر بروید.