Node.js ile Proxy Kullanımı: axios, undici ve fetch Örnekleri

Node.js’te proxy kullanmanın üç yaygın yolu vardır: yerleşik fetch için Node’u NODE_USE_ENV_PROXY=1 ile başlatıp HTTPS_PROXY değişkenini tanımlamak, undici paketinin ProxyAgent sınıfını isteğe dispatcher olarak vermek ya da axios’ta proxy ayarını kullanmak. Proxy adresi her durumda http://USER:PASSWORD@host:port biçimindedir; SOCKS5 için socks-proxy-agent veya undici’nin Socks5ProxyAgent sınıfı gerekir.

Hangi yolu seçeceğiniz kullandığınız HTTP istemcisine bağlı. Node.js, http.request ve fetch için proxy ayarını kendiliğinden okumaz; ya ortam değişkeni desteğini açarsınız ya da her istemciye proxy’yi ayrıca tanıtırsınız. Örneklerde WeProxy gateway adresi gw.weproxy.com.tr:8989 kullanılıyor. USER ve PASSWORD müşteri panelindeki bilgilerinizdir.

Node.js’te proxy adresi nasıl yazılır?

Bütün istemciler proxy’yi aynı URL biçiminde kabul eder:

şema://kullanıcı:parola@host:port

Şema proxy sunucusunun protokolüdür. Hedef site HTTPS olsa da HTTP proxy adresi http:// ile başlar; istemci proxy’ye CONNECT isteği gönderir ve TLS bağlantısı bu tünelin içinde kurulur. Adresi https:// ile yazarsanız istemci proxy’nin kendisiyle TLS konuşmaya çalışır. undici bu durumda ERR_SSL_WRONG_VERSION_NUMBER hatası verir. HTTP proxy ile SOCKS5 arasındaki farkı HTTP vs SOCKS5 yazısı anlatıyor.

Parolada @, :, / veya # geçiyorsa URL’ye koymadan önce encodeURIComponent ile kodlayın. Kodlanmamış bir @ adresin ayrıştırılmasını bozar ve undici TypeError: Invalid URL hatası verir:

const user = encodeURIComponent(process.env.WEPROXY_USERNAME);
const pass = encodeURIComponent(process.env.WEPROXY_PASSWORD);
export const PROXY = `http://${user}:${pass}@gw.weproxy.com.tr:8989`;

Kimlik bilgilerini ortam değişkeninde ya da bir secret yöneticisinde tutun; böylece kod Git’e gittiğinde parola gitmez. Panelden ip:port:user:pass biçiminde liste aldıysanız proxy format dönüştürücü satırları URL biçimine çevirir. IPv6 adresleri ve socks5h gibi ayrıntılar proxy formatları rehberinde var.

Node.js yerleşik fetch ile proxy nasıl kullanılır?

Node.js 24 ve 22.21 sonrası sürümlerde yerleşik fetch, HTTP_PROXY, HTTPS_PROXY ve NO_PROXY değişkenlerini okuyabilir. Bu davranış varsayılan olarak kapalıdır ve NODE_USE_ENV_PROXY=1 değişkeniyle ya da --use-env-proxy bayrağıyla açılır. Bayrak verilmezse Node değişkenleri görmezden gelir ve istek doğrudan sizin IP’nizden çıkar.

export HTTPS_PROXY="http://USER:[email protected]:8989"
export HTTP_PROXY="$HTTPS_PROXY"
export NO_PROXY="localhost,127.0.0.1"
NODE_USE_ENV_PROXY=1 node app.mjs

PowerShell’de aynı ayar şöyle yapılır:

$env:HTTPS_PROXY = "http://USER:[email protected]:8989"
$env:HTTP_PROXY = $env:HTTPS_PROXY
node --use-env-proxy app.mjs

app.mjs dosyasında proxy’ye dair hiçbir satır olmaz:

const res = await fetch('https://api.ipify.org?format=json', {
  signal: AbortSignal.timeout(30_000),
});
console.log(await res.json()); // { ip: '<proxy çıkış IP’si>' }

Güncel sürümlerde bu bayrak node:http ve node:https modüllerinin global agent’larını da proxy’ye yönlendirir; https.get gibi eski tarz çağrılar kod değişmeden proxy’den çıkar. Ayrıntılar Node.js CLI belgesinde. Yöntem, mevcut bir uygulamayı koduna dokunmadan proxy’ye almak için uygundur. Tüm süreç tek proxy kullanır; istek başına farklı proxy gerekiyorsa sıradaki yönteme geçin.

undici ProxyAgent ile proxy nasıl kullanılır?

undici, Node.js’in fetch uygulamasının altındaki HTTP istemcisidir ve npm’de ayrı paket olarak da yayınlanır. ProxyAgent sınıfı proxy’yi istek düzeyinde verir:

npm install undici

import { ProxyAgent, fetch } from 'undici';
import { PROXY } from './proxy.mjs';

const dispatcher = new ProxyAgent(PROXY);

const res = await fetch('https://api.ipify.org?format=json', {
  dispatcher,
  signal: AbortSignal.timeout(30_000),
});
console.log(await res.json());

await dispatcher.close();

fetch fonksiyonunu da ProxyAgent ile aynı paketten içe aktarın. Node’un içindeki undici sürümü npm’deki sürümden geride olabilir. Node.js 24’ün yerleşik fetch fonksiyonuna npm’deki undici 8’in ProxyAgent nesnesini verdiğinizde istek fetch failed ile düşer, alttaki neden invalid onRequestStart method olur.

Parolayı URL’ye gömmek istemiyorsanız kimlik bilgisini başlık değeri olarak verebilirsiniz. Bu biçimde yüzde kodlamasına gerek kalmaz:

const basic = Buffer.from(
  `${process.env.WEPROXY_USERNAME}:${process.env.WEPROXY_PASSWORD}`
).toString('base64');

const dispatcher = new ProxyAgent({
  uri: 'http://gw.weproxy.com.tr:8989',
  token: `Basic ${basic}`,
});

Uygulamadaki bütün fetch çağrılarını proxy’den geçirmek için setGlobalDispatcher(new ProxyAgent(PROXY)) kullanılır. Ortam değişkenlerini okuyan ama süreç bayrağı istemeyen bir seçenek de var: EnvHttpProxyAgent, HTTPS_PROXY ve NO_PROXY değerlerini kendisi okur. Seçeneklerin tam listesi undici ProxyAgent belgesinde.

axios ile proxy nasıl kullanılır?

axios, Node.js’te proxy’yi proxy ayarıyla alır. Kimlik bilgileri ayrı alanlarda verildiği için özel karakterleri kodlamanız gerekmez:

import axios from 'axios';

const client = axios.create({
  proxy: {
    protocol: 'http',
    host: 'gw.weproxy.com.tr',
    port: 8989,
    auth: {
      username: process.env.WEPROXY_USERNAME,
      password: process.env.WEPROXY_PASSWORD,
    },
  },
  timeout: 30_000,
});

const { data } = await client.get('https://api.ipify.org?format=json');
console.log(data);

Güncel axios sürümleri HTTPS hedefler için proxy’ye CONNECT tüneli açar. 1.16.1 sürümünde, bazı yapılandırmalarda HTTPS isteğin içeriğinin HTTP proxy’ye şifresiz gidebildiği bir hata düzeltildi (axios değişiklik kaydı). Eski bir sürümle çalışıyorsanız axios’u güncelleyin ya da tüneli https-proxy-agent paketine bırakın:

import axios from 'axios';
import { HttpsProxyAgent } from 'https-proxy-agent';
import { PROXY } from './proxy.mjs';

const client = axios.create({
  httpsAgent: new HttpsProxyAgent(PROXY),
  proxy: false,
});

axios varsayılan olarak HTTPS_PROXY ve NO_PROXY değişkenlerini okur; proxy: false satırı olmazsa ortamdaki proxy sizin agent’ınızla çakışabilir. Parolası yüzde kodlanmış bir HTTPS_PROXY değerini ise axios proxy’ye kodlu haliyle gönderir ve sonuç 407 olur. Parolada özel karakter varsa axios’ta auth nesnesini kullanın.

Node.js’te SOCKS5 proxy nasıl kullanılır?

Ne yerleşik fetch ne de axios SOCKS5’i kendi başına konuşur. axios ve node:https için socks-proxy-agent paketi kullanılır:

npm install socks-proxy-agent

import axios from 'axios';
import { SocksProxyAgent } from 'socks-proxy-agent';

const user = encodeURIComponent(process.env.WEPROXY_USERNAME);
const pass = encodeURIComponent(process.env.WEPROXY_PASSWORD);
const agent = new SocksProxyAgent(`socks5h://${user}:${pass}@gw.weproxy.com.tr:8989`);

const client = axios.create({ httpAgent: agent, httpsAgent: agent, proxy: false });
console.log((await client.get('https://api.ipify.org')).data);

socks5h şeması alan adı çözümünü proxy’ye bırakır; socks5 yazarsanız hedef alan adı kendi DNS sunucunuzda çözülür. undici kullanıyorsanız Socks5ProxyAgent sınıfı aynı işi görür ve alan adını her zaman proxy tarafında çözdürür. Sınıf henüz deneysel olarak işaretli, ilk kullanımda ExperimentalWarning yazdırır:

import { Socks5ProxyAgent, fetch } from 'undici';

const dispatcher = new Socks5ProxyAgent(`socks5://${user}:${pass}@gw.weproxy.com.tr:8989`);
const res = await fetch('https://api.ipify.org', { dispatcher });
console.log(await res.text());

SOCKS5 desteği pakete göre değişir. Rotating Residential IPv4 HTTP ve SOCKS5 sunar; gerçek SIM’li Mobil 5G Proxy yalnız HTTP ile çalışır. Oyun ve VoIP gibi UDP trafiği bu istemcilerle taşınmaz; UDP gereken kurulumlar UDP proxy rehberinde.

axios, undici ve fetch karşılaştırması

Yeni bir projede undici tek paketle istek başına proxy, SOCKS5 ve bağlantı havuzu ayarını getirir. Kod tabanı axios üzerine kuruluysa istemciyi değiştirmeye gerek yok; proxy ayarı ya da https-proxy-agent yeterli.

Rotating ve sticky IP Node.js’te nasıl yönetilir?

Rotating bir gateway’de proxy adresi aynı kalır, çıkış IP’si havuzdan değişir. Node.js tarafında dikkat edilecek konu bağlantı yeniden kullanımıdır. undici ProxyAgent her hedef için açtığı tüneli sonraki isteklerde kullanır; Node.js 19’dan beri http ve https global agent’larında keepAlive varsayılan olarak açıktır. IP değişimi yeni bağlantıda uygulanıyorsa aynı agent’tan giden art arda istekler aynı IP’den çıkabilir. Gateway’in istek başına mı bağlantı başına mı döndüğünü görmek için aynı agent ile iki kez, ardından iki ayrı agent ile iki kez api.ipify.org sorgulayın.

Login, sepet veya çok adımlı form gibi işlerde ise istekler boyunca aynı IP gerekir. WeProxy residential ve mobil havuzlarında bunun için kullanıcı adına bir session kimliği eklenir. Kullanıcı adının biçimi ve oturum süresi ürüne göre değiştiği için ikisini de panelden alın. Kodda her hesaba ayrı agent açmak yeterlidir:

import { ProxyAgent, fetch } from 'undici';

// Kullanıcı adları panelden kopyalanır; her profil kendi session ID’sini taşır.
const PROFILES = {
  'hesap-1': 'USER_WITH_SESSION_1',
  'hesap-2': 'USER_WITH_SESSION_2',
};
const pass = encodeURIComponent(process.env.WEPROXY_PASSWORD);

const agents = Object.fromEntries(
  Object.entries(PROFILES).map(([name, user]) => [
    name,
    new ProxyAgent(`http://${encodeURIComponent(user)}:${pass}@gw.weproxy.com.tr:8989`),
  ])
);

for (const [name, dispatcher] of Object.entries(agents)) {
  const res = await fetch('https://api.ipify.org', { dispatcher });
  console.log(name, await res.text());
}

İki profil aynı session kimliğini paylaşmamalı; paylaşırsa hedef site iki ayrı kullanıcıyı aynı IP’den görür. Hangi işin sticky, hangisinin rotating istediğini sticky mi rotating mi rehberi senaryo tablosuyla anlatıyor. İki oturum türünü bir arada sunan paket rotating residential proxy sayfasında.

Çok sayıda URL tarayacaksanız Promise.all ile hepsini aynı anda başlatmak yerine eşzamanlılığı sınırlayın. Ek paket gerektirmeyen küçük bir havuz:

async function runPool(items, limit, worker) {
  const results = [];
  let next = 0;
  const lanes = Array.from({ length: limit }, async () => {
    while (next < items.length) {
      const i = next++;
      results[i] = await worker(items[i]).catch((err) => err);
    }
  });
  await Promise.all(lanes);
  return results;
}

const urls = Array(20).fill('https://api.ipify.org');
const ips = await runPool(urls, 5, async (url) =>
  (await fetch(url, { dispatcher: agents['hesap-1'] })).text()
);

Burada sınırı belirleyen hedef sitedir: aynı IP’den gelen ani istek yığını hedefin hız sınırına takılır ve 429 döner.

Proxy’nin çalıştığını nasıl doğrularsınız?

En kısa test, çıkış IP’sini proxy’siz ve proxy’li sorgulayıp karşılaştırmaktır:

import { ProxyAgent, fetch as undiciFetch } from 'undici';
import { PROXY } from './proxy.mjs';

const dispatcher = new ProxyAgent(PROXY);
const direct = await (await fetch('https://api.ipify.org')).text();
const viaProxy = await (await undiciFetch('https://api.ipify.org', { dispatcher })).text();

console.log({ direct, viaProxy });
if (direct === viaProxy) throw new Error('İstek proxy’den çıkmıyor');

İki değer aynıysa proxy ayarı isteğe ulaşmıyordur. Yerleşik fetch kullanıyorsanız NODE_USE_ENV_PROXY bayrağını, axios’ta proxy: false ile ortam değişkenlerinin çakışmasını, her durumda NO_PROXY listesini kontrol edin. Proxy IP’sinin ülkesini ve ağını My IP aracı gösterir. Proxy’yi koddan bağımsız test etmek için proxy checker aracını kullanın; orada çalışıp Node’da çalışmayan bir proxy, sorunun istemci ayarında olduğunu gösterir. Aynı testi terminalden yapmak isterseniz cURL ile proxy kullanımı yazısındaki komutlar işinizi görür.

Node.js proxy hataları ve çözümleri

Aynı sorun her istemcide başka bir hata olarak görünür. Tablodaki karşılıklar yerel bir test proxy’sinde Node.js 24, undici 8, axios 1.21 ve https-proxy-agent 9 ile alındı:

undici hatanın gerçek nedenini err.cause içinde saklar; yalnız err.message yazdırırsanız her hata “fetch failed” görünür. Log’a err.cause?.code ve err.cause?.message değerlerini de yazın.

407 aldığınızda önce parolanın kodlandığını, sonra paketin aktif olduğunu kontrol edin. IP whitelist ile çalışıyorsanız kodun çalıştığı sunucunun çıkış IP’si panelde kayıtlı olmalı; yerelde çalışan script sunucuya taşındığında 407 başladıysa neden budur. Yöntemlerin ürünlere göre dağılımı proxy kimlik doğrulama rehberinde. 407 için yeniden deneme yapmayın; aynı kimlik bilgisiyle sonuç değişmez.

429, 502, 503 ve 504 geçici olabilir ve aralığı giderek açılan yeniden deneme ister. Her kodun hangi katmandan geldiği proxy hata kodları rehberinde anlatılıyor. Bağlantı sürekli zaman aşımına düşüyorsa kurumsal ağınız ya da bulut sağlayıcınız 8989 portuna çıkışı kapatıyor olabilir. Sertifika hatası alırsanız NODE_TLS_REJECT_UNAUTHORIZED=0 ile doğrulamayı kapatmayın; bu ayar bütün süreçte TLS doğrulamasını devre dışı bırakır.

Node.js ile proxy kullanırken uyum ve güvenlik

Veri toplayan bir script yazıyorsanız istekler proxy’den çıksa da hedefin robots.txt dosyasına (RFC 9309) ve kullanım şartlarına uyun, istek hızını sitenin kaldırabileceği düzeyde tutun. Kişisel veri işliyorsanız KVKK ve GDPR yükümlülükleri proxy’den bağımsız olarak geçerlidir. WeProxy hizmetlerinde izin verilen ve verilmeyen kullanımlar kabul edilebilir kullanım sayfasında yazılı.

Proxy URL’si parolayı içerdiği için hata mesajlarında ve loglarda kolayca açığa çıkar. Log’a yazmadan önce new URL(PROXY) ile adresi ayrıştırıp password alanını silin. Kurulum adımları Node.js entegrasyonu sayfasında, çalıştırılabilir örnek proje weproxy-io/nodejs-proxy deposunda. Tarayıcı otomasyonu için Puppeteer entegrasyonuna, aynı işleri Python’da yapmak için Python ile proxy kullanımı yazısına bakabilirsiniz. Scraping işlerinde IP türü ve oturum seçimi web scraping sayfasında.