---
title: "Прокси в Node.js: fetch, undici и SOCKS5 | Proxonym"
description: "Как использовать прокси в Node.js с fetch и ProxyAgent из undici: аутентификация, IP с ротацией и sticky-IP, геотаргетинг, SOCKS5 и обработка повторных попыток."
url: https://proxonym.com/ru/integrations/nodejs
updated: 2026-10-02T03:03:46+00:00
---

# Как использовать прокси в Node.js

Node.js отправляет fetch-запросы через прокси с помощью ProxyAgent из undici. В руководстве: аутентификация на шлюзе Proxonym, ротация и закрепление IP, выбор местоположения, SOCKS5 и повторные попытки при ошибках.

- 6 шагов
- Настройка за 12 мин
- Готовый код для копирования

Перед началом работы

- Node.js 22 или новее
- undici 8 или новее, а для SOCKS5 — socks-proxy-agent
- Тариф Proxonym на резидентные или мобильные прокси

Параметры подключения

- **Хост**: `gw.proxonym.com`
- **HTTP**: `8000`
- **SOCKS5**: `1080`
- **Пользователь**: `USERNAME-country-us`

1. **Установите пакеты**: Установите undici для работы через HTTP-прокси и socks-proxy-agent, если планируете использовать SOCKS5. Сохраняйте примеры как файлы `.mjs`, чтобы `import` и `await` верхнего уровня работали без дополнительной настройки. Shell `npm install undici socks-proxy-agent`
2. **Отправьте запрос через шлюз**: Создайте ProxyAgent с адресом шлюза и токеном Basic для заголовка Proxy-Authorization, затем передайте его в `fetch` как dispatcher. Скрипт выведет выходной IP, который видит целевой сайт. JavaScript `// check-ip.mjs import { fetch, ProxyAgent } from 'undici'; const dispatcher = new ProxyAgent({ uri: 'http://gw.proxonym.com:8000', token: 'Basic ${Buffer.from('USERNAME:PASSWORD').toString('base64')}', }); const res = await fetch('https://api.ipify.org', { dispatcher }); console.log('Exit IP:', await res.text()); await dispatcher.close();`
3. **Меняйте IP или сохраняйте один и тот же**: ProxyAgent повторно использует свои подключения, и каждое подключение сохраняет один выходной IP. Для ротации создавайте новый агент на каждый запрос или используйте один агент с ID сессии, заданным через `-session-`, чтобы сохранять тот же IP до 120 минут. JavaScript `// sessions.mjs import { randomBytes } from 'node:crypto'; import { fetch, ProxyAgent } from 'undici'; function proxonymAgent({ country, state, city, asn, session, lifetime = 30 } = {}) { let user = 'USERNAME'; if (country) user += '-country-${country}'; if (state) user += '-state-${state}'; if (city) user += '-city-${city}'; if (asn) user += '-asn-${asn}'; if (session) user += '-session-${session}-lifetime-${lifetime}'; return new ProxyAgent({ uri: 'http://gw.proxonym.com:8000', token: 'Basic ${Buffer.from('${user}:PASSWORD').toString('base64')}', }); } // Rotating: a new agent opens a new connection, so each request gets a new IP for (let i = 0; i < 3; i++) { const agent = proxonymAgent({ country: 'us' }); const res = await fetch('https://api.ipify.org', { dispatcher: agent }); console.log('rotating', await res.text()); await agent.close(); } // Sticky: one agent and one session ID keep the same IP for up to 30 minutes const sticky = proxonymAgent({ country: 'us', session: randomBytes(4).toString('hex') }); for (let i = 0; i < 3; i++) { const res = await fetch('https://api.ipify.org', { dispatcher: sticky }); console.log('sticky', await res.text()); } await sticky.close();`
4. **Укажите страну, штат, город или ASN**: Передайте параметры местоположения во вспомогательную функцию `proxonymAgent()` из предыдущего шага. Используйте коды стран ISO строчными буквами и подчёркивания вместо пробелов, например `{ country: 'us', state: 'new_york' }` или `{ country: 'us', asn: 7922 }`. JavaScript `const agent = proxonymAgent({ country: 'de', city: 'berlin' }); const res = await fetch('https://ipinfo.io/json', { dispatcher: agent }); const { ip, city, country } = await res.json(); console.log(ip, city, country); await agent.close();`
5. **Используйте SOCKS5-эндпоинт**: Поддержка SOCKS5 в undici всё ещё помечена как экспериментальная, поэтому в этом примере используется socks-proxy-agent с модулем `https`; тот же агент работает с axios и другими клиентами, которые принимают агент. Схема `socks5h://` позволяет прокси самому разрешать имена хостов. JavaScript `// socks5.mjs import https from 'node:https'; import { SocksProxyAgent } from 'socks-proxy-agent'; const agent = new SocksProxyAgent('socks5h://USERNAME-country-gb:PASSWORD@gw.proxonym.com:1080'); https.get('https://api.ipify.org', { agent }, (res) => { let body = ''; res.on('data', (chunk) => (body += chunk)); res.on('end', () => console.log('Exit IP:', body)); });`
6. **Повторяйте запросы при ошибках шлюза**: Когда шлюз отклоняет туннель, промис `fetch` завершается с ошибкой, а самый вложенный `err.cause` указывает статус шлюза. При 429, 502 и 504 повторяйте запрос после короткой паузы, а при 407, 402 или 403 останавливайтесь: они указывают на проблему с учётными данными, балансом или на заблокированный целевой сайт. JavaScript `// retry.mjs import { fetch, ProxyAgent } from 'undici'; const dispatcher = new ProxyAgent({ uri: 'http://gw.proxonym.com:8000', token: 'Basic ${Buffer.from('USERNAME-country-us:PASSWORD').toString('base64')}', }); // The innermost cause carries the gateway status, e.g. "Proxy response (407) !== 200 when HTTP Tunneling" function rootCause(err) { let cause = err; while (cause?.cause) cause = cause.cause; return cause; } async function fetchWithRetry(url, tries = 3) { for (let attempt = 1; ; attempt++) { try { const res = await fetch(url, { dispatcher, signal: AbortSignal.timeout(60_000) }); if ((res.status !== 429 && res.status < 500) || attempt === tries) return res; await res.body?.cancel(); } catch (err) { const reason = rootCause(err).message; console.error('attempt ${attempt}:', reason); // 402, 403 and 407 will not go away on a retry if (/\((402|403|407)\)/.test(reason) || attempt === tries) throw err; } await new Promise((resolve) => setTimeout(resolve, 1000 * attempt)); } } const res = await fetchWithRetry('https://example.com'); console.log('Status:', res.status); await dispatcher.close();`

## Часто задаваемые вопросы

### Можно ли использовать встроенный в Node.js fetch с прокси?

Да, двумя способами. Последние версии, например Node.js 24, направляют глобальный fetch через HTTPS_PROXY, если задать NODE_USE_ENV_PROXY=1, — это подходит для одного фиксированного URL прокси. Чтобы управлять сессиями и местоположением для каждого запроса, установите undici и импортируйте из него и fetch, и ProxyAgent: тогда клиент и dispatcher всегда будут одной версии.

### Как использовать Proxonym с axios?

Установите https-proxy-agent, создайте new HttpsProxyAgent("http://USERNAME:PASSWORD@gw.proxonym.com:8000") и передайте его как httpsAgent, задав proxy значение false. Для SOCKS5 точно так же передайте SocksProxyAgent. Каждый агент держит пул подключений, поэтому создавайте отдельный агент для каждой sticky-сессии, которую хотите запускать параллельно.

### Почему мои запросы сохраняют один и тот же IP без параметра сессии?

Шлюз назначает IP на каждое подключение, а undici держит подключения открытыми, поэтому последовательные запросы через один агент к одному и тому же хосту идут через один туннель. Если каждый вызов должен выходить с другого IP, закрывайте агент между запросами, создавайте новый агент для каждого запроса или добавляйте к каждому запросу случайный ID сессии.

### Что означает ошибка Proxy response (407) !== 200 when HTTP Tunneling?

Это сообщение, которое undici прикрепляет к запросу CONNECT, отклонённому шлюзом; его можно найти в самом вложенном err.cause, а число в нём — статус шлюза. 407 указывает на неверные учётные данные, 402 — на пустой баланс или истёкший тариф, а 403 — на целевой сайт, заблокированный по правилам допустимого использования. 502 и 504 — временные ошибки, поэтому повторите запрос с нарастающей паузой.

Советы и подводные камни

- Импортируйте fetch и ProxyAgent из одного и того же пакета undici: если передать ProxyAgent из npm встроенному в Node.js fetch, при расхождении версий возможен сбой.
- Запросы через один агент повторно используют его подключения, а значит, и выходной IP, поэтому для ротации нужен новый агент или новое подключение.
- В axios передайте HttpsProxyAgent из пакета https-proxy-agent как httpsAgent и задайте proxy значение false, чтобы axios не применял собственную обработку прокси.
- Читайте учётные данные из process.env, а не прописывайте их в коде, особенно если код хранится в общем репозитории.

Читайте также

- [Как парсить выдачу Google: собственные прокси или SERP API](https://proxonym.com/ru/blog/scrape-google-search-results)
- [Ротационные или sticky-прокси: какой тип сессии выбрать](https://proxonym.com/ru/blog/rotating-vs-sticky-sessions)

Застряли на каком-то шаге?

Большинство сбоев сводится к коду ошибки. Сначала проверьте его, затем протестируйте сам прокси отдельно.

- [Справочный центр](https://proxonym.com/ru/help)
- [Коды ошибок шлюза](https://proxonym.com/ru/docs#errors-and-troubleshooting)
- [Проверить прокси](https://proxonym.com/ru/proxy-checker)

## Другие руководства по интеграции

[Все интеграции](https://proxonym.com/ru/integrations)

- [Playwright (JavaScript)](https://proxonym.com/ru/integrations/playwright)
- [Puppeteer (JavaScript)](https://proxonym.com/ru/integrations/puppeteer)
- [AdsPower (Антидетект-браузер)](https://proxonym.com/ru/integrations/adspower)
