إعداد البروكسي في Node.js: axios وgot وfetch وundici (دليل 2026)

يتعامل كل عميل HTTP في Node.js مع البروكسيات بطريقة مختلفة، ونصفها لا يتعامل مع مصادقة البروكسي على الإطلاق دون حزمة مساعدة. يتجاهل axios بصمت خيار proxy الخاص به للأهداف عبر HTTPS في بعض الإصدارات، ولا يملك fetch الأصلي أي خيار للبروكسي على الإطلاق، ورسائل الأخطاء — ECONNRESET أو 407 أو مجرد تعليق — لا تخبرك بشيء.

هذا هو المرجع الكامل والعملي لتوجيه axios وgot وnode-fetch وfetch الأصلي (undici) وsuperagent عبر بروكسيات سكنية مع مصادقة. إنه رفيق Node لأدلة Python لدينا (requests/httpx/aiohttp، Scrapy). تستخدم جميع الأمثلة صيغة العنصر النائب القياسية — استبدلها ببيانات الاعتماد الحقيقية الخاصة بك:

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

القاعدة الوحيدة التي تمنع معظم الأخطاء

لا تستخدم خيارات proxy المدمجة. استخدم وكيل بروكسي (proxy agent). تفوّض عملاء HTTP في Node معالجة الاتصال إلى كائن "وكيل" (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,    // 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

شيئان يفوتان على الناس: يجب عليك ضبط كلا الخيارين httpAgent وhttpsAgent (يختار axios بناءً على مخطط الهدف)، ويجب عليك ضبط proxy: false حتى لا يحاول axios أيضًا تطبيق متغيرات البيئة 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 بدلًا من ذلك — نفس الواجهة، إضافة إلى توليد ترويسات شبيهة بالمتصفح ومحاكاة بصمة HTTP/2 (ولماذا يهم ذلك: شرح JA3/JA4).

fetch الأصلي / undici (Node 18+)

يأتي fetch المدمج في Node من undici، وهو يتجاهل متغيرات بيئة البروكسي ولا يملك خيار agent. الطريقة في undici هي الموزّع (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());

ملاحظة: ProxyAgent في undici يدعم بروكسي HTTP فقط. لاستخدام SOCKS5 مع fetch الأصلي، إما أن تضع أمامه معيد توجيه محلي أو تستخدم عميلًا يقبل وكلاء socks (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 });

التدوير: هوية جديدة لكل طلب مقابل الجلسات الثابتة

مع بوابة سكنية دوّارة، لا تدير قوائم عناوين IP — تمنحك البوابة منفذ خروج جديدًا لكل اتصال، أو تحتفظ بمنفذ خروج واحد لكل معرّف جلسة. في Node يُترجم ذلك بوضوح إلى وكيل واحد لكل هوية:

// 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");

أعد استخدام الوكيل لتجميع الاتصالات ضمن الهوية الواحدة؛ لا تشارك أبدًا وكيلًا واحدًا عبر هويات مختلفة. أما متى تدوّر ومتى تثبّت فهو موضوع قائم بذاته — راجع الجلسات الثابتة مقابل الدوّارة.

جدول استكشاف الأخطاء وإصلاحها

العَرَض	السبب	الحل
407 Proxy Authentication Required	بيانات الاعتماد لا تصل إلى البروكسي	ضع user:pass في عنوان الوكيل، وليس في إعداد العميل
axios يعمل على http:// ويفشل على https://	تم ضبط httpAgent فقط	اضبط httpsAgent أيضًا، وproxy: false
ECONNRESET فورًا	منفذ خاطئ / بروتوكول خاطئ (منفذ HTTP مع وكيل SOCKS)	طابق نوع الوكيل مع المنفذ
تسريبات DNS / فشل أسماء المضيفين الداخلية	socks5:// يحل DNS محليًا	استخدم socks5h:// — الحرف h يرسل أسماء المضيفين عبر البروكسي
fetch الأصلي يتجاهل HTTP_PROXY	undici لا يقرأ متغيرات البيئة	مرّر dispatcher بشكل صريح
يعمل محليًا، 403 على الموقع المستهدف	ليست مشكلة بروكسي — بل بصمة TLS	got-scraping أو متصفح حقيقي؛ راجع دليل TLS

الخلاصة

• استخدم دائمًا حزم الوكلاء (socks-proxy-agent / https-proxy-agent)؛ لا تثق أبدًا بخيارات البروكسي المدمجة.
• axios: كلا الوكيلين + proxy: false. got: agent: {http, https}. fetch الأصلي: موزّع ProxyAgent من undici.
• استخدم socks5h:// حتى يُحل DNS عبر البروكسي — دون تسريبات.
• وكيل واحد لكل هوية: معرّفات الجلسات الثابتة تبقي ملفات تعريف الارتباط وعنوان IP للخروج يتحركان معًا.
• ما زلت محظورًا رغم بروكسي يعمل؟ تلك بصمة، وليست البروكسي — انتقل إلى got-scraping أو متصفح.