Прокси в Node.js: переменные окружения, fetch, axios и SOCKS5

Встроенная поддержка через переменные окружения

В документации Node.js по HTTP описана встроенная поддержка прокси, которая читает переменные HTTP_PROXY, HTTPS_PROXY и NO_PROXY (в нижнем или верхнем регистре). По умолчанию она выключена: её включают переменной NODE_USE_ENV_PROXY=1 или флагом --use-env-proxy, а в документации она помечена Stability 1.1, то есть находится в активной разработке. Переменная NODE_USE_ENV_PROXY появилась в Node.js v24.0.0 и v22.21.0, флаг --use-env-proxy и опция proxyEnv у http.Agent — в v24.5.0 и v22.21.0; в более старых версиях переменная игнорируется. Для fetch() она действует с v24.0.0 и v22.21.0, а для http.request() и https.request() через глобальный агент — с v24.5.0 и v22.21.0, поэтому в v24.0.0–v24.4.x она затрагивает только fetch().

Документированные форматы URL прокси — http:// и https://, учётные данные записываются как http://username:password@host:port. Поэтому встроенная поддержка рассчитана на HTTP-прокси, SOCKS5 она не охватывает.

Встроенная поддержка через переменные окружения: пример

NODE_USE_ENV_PROXY=1 \
HTTPS_PROXY="http://USERNAME:[email protected]:2222" \
node app.js

Замените USERNAME и PASSWORD значениями из «Мои активы». Если запрашиваете обычные адреса http://, задайте и HTTP_PROXY. Для модулей http и https нужен Node.js v24.5.0 или v22.21.0 и новее; fetch() учитывает переменную уже с v24.0.0.

Встроенная поддержка через переменные окружения, продолжение

В документации также описан http.setGlobalProxyFromEnv() (добавлен в v25.4.0 и v24.14.0) для включения этой поддержки из кода. Node.js подчёркивает, что встроенная поддержка прокси не является средством анонимности и что прокси видит метаданные соединения, поэтому используйте только те прокси, которым доверяете.

• Источники:
• Документация Node.js: HTTP, встроенная поддержка прокси
• Документация Node.js: параметры командной строки, --use-env-proxy

fetch и ProxyAgent из undici

Установите пакет undici и передайте ProxyAgent как dispatcher. В актуальной документации undici сказано, что ProxyAgent направляет запросы через HTTP-, HTTPS- или SOCKS5-прокси (проверьте, что установленная версия undici поддерживает URL socks5:; в примере ниже используется HTTP-порт) и что учётные данные в URL прокси перед использованием декодируются.

fetch и ProxyAgent из undici: пример

import { ProxyAgent, fetch } from 'undici'

const user = encodeURIComponent('USERNAME')
const pass = encodeURIComponent('PASSWORD')
const dispatcher = new ProxyAgent(`http://${user}:${pass}@proxy.proxy302.com:2222`)

const res = await fetch('https://ipinfo.io/json', { dispatcher })
console.log(await res.json())

Кодирование пароля экранирует символы вроде @, : и /, которые иначе ломают URL.

• Источники:
• Документация undici: ProxyAgent
• MDN: encodeURIComponent()

axios

Документация axios позволяет задать в запросе объект proxy с protocol, host, port и auth (логин и пароль). Для адреса https:// axios 1.16.1 и новее открывает через прокси туннель CONNECT; в 1.16.0 и более ранних версиях адаптер http для Node отправляет запрос HTTP-прокси открытым текстом, как обычный прокси-запрос, без туннеля и без сквозного TLS, поэтому сначала обновите axios (начиная с 1.17.0 внутри туннеля также сохраняются настройки TLS вашего собственного httpsAgent). Если сам прокси работает по HTTPS, укажите protocol https; для HTTP-порта Proxy302 2222 protocol — http.

axios: пример

import axios from 'axios'

const res = await axios.get('https://ipinfo.io/json', {
  proxy: {
    protocol: 'http',
    host: 'proxy.proxy302.com',
    port: 2222,
    auth: { username: 'USERNAME', password: 'PASSWORD' },
  },
})
console.log(res.data)

В объекте proxy логин и пароль — отдельные поля, поэтому URL-кодирование не нужно.

• Источники:
• Документация axios: конфигурация запроса, proxy

Прокси-агенты, включая SOCKS5

Проект proxy-agents предоставляет классы http.Agent для встроенных модулей http и https. https-proxy-agent подключается к HTTP- или HTTPS-прокси методом CONNECT, socks-proxy-agent — к SOCKS-прокси. В исходном коде обоих пакетов логин и пароль берутся из URL прокси и декодируются, а socks-proxy-agent принимает схемы socks4, socks4a, socks5 и socks5h.

Прокси-агенты, включая SOCKS5: пример

import https from 'node:https'
import { SocksProxyAgent } from 'socks-proxy-agent'

const agent = new SocksProxyAgent(
  `socks5h://${encodeURIComponent('USERNAME')}:${encodeURIComponent('PASSWORD')}@proxy.proxy302.com:3333`
)
https.get('https://ipinfo.io/json', { agent }, (res) => res.pipe(process.stdout))

При socks5h имя хоста в IP-адрес преобразует сам прокси. SOCKS5 у Proxy302 — порт 3333; для HTTP-прокси используйте HttpsProxyAgent и порт 2222.

• Источники:
• Проект proxy-agents: https-proxy-agent и socks-proxy-agent

Проверьте выход

Запросите https://ipinfo.io/json через прокси, как в примерах выше. Поля country и org должны описывать прокси, а не ваше подключение. Если виден ваш собственный адрес, запрос прокси не использовал: проверьте, что переменная задана до запуска Node, а агент или dispatcher передан именно в этот вызов. Поля объяснены в руководстве по проверке местоположения прокси.

• руководстве по проверке местоположения прокси

Типичные ошибки

По списку ошибок Node.js, ECONNREFUSED означает, что целевая машина активно отказала в соединении, что обычно происходит, когда там не запущена служба: проверьте адрес и порт. ETIMEDOUT означает, что другая сторона не ответила вовремя: проверьте порт, сеть и заданный таймаут. ENOTFOUND — сбой DNS-запроса: проверьте имя хоста. Статус 407 означает, что прокси не принял учётные данные; см. руководство по ошибке аутентификации. Убедитесь также, что протокол соответствует порту: HTTP — 2222, SOCKS5 — 3333; проверки по шагам есть в руководстве по ошибке подключения.

• руководство по ошибке аутентификации
• руководстве по ошибке подключения

• Источники:
• Документация Node.js: типичные системные ошибки

Как это сделать с Proxy302

Любому из этих клиентов нужны только адрес, порт, логин и пароль прокси Proxy302. Трафик ротационных резидентных прокси оплачивается за ГБ, страна выхода задаётся при создании прокси; HTTP — порт 2222, SOCKS5 — порт 3333 на proxy.proxy302.com. Статический ISP IP фиксирован на весь срок аренды и не ротируется. В таблице — выходы в 7 странах при нашей последней почасовой проверке; зонд отправляет запрос к ChatGPT, это лишь пример целевого сайта для проверки сети. Прокси не меняет условия ChatGPT, и список поддерживаемых стран OpenAI по-прежнему действует; он есть в руководстве по поддерживаемым странам. Подробности — на странице ротационных резидентных прокси и в руководстве по проверке местоположения прокси.

• странице ротационных резидентных прокси
• руководстве по проверке местоположения прокси
• руководстве по поддерживаемым странам

Измеренные выходы: ChatGPT, 7 стран

Почасовая проверка зонда Proxy302, 25 октября 2026, 08:29 UTC: по одному запросу к ChatGPT из каждой страны через ротационный резидентный выход, по публичной точке входа Proxy302. Публично показаны только первые три октета IP. Один замер на страну, не среднее; следующие проверки будут отличаться.

• Источники:
• Почасовая проверка связности Proxy302

Как это сделать с Proxy302: шаги

1. Шаг 1

   Откройте страницу ротационных резидентных прокси, выберите линию, оставьте протокол HTTP или выберите SOCKS5 и нажмите «Проверить цену и создать».

2. Шаг 2

   Откройте «Мои активы» (раздел консоли со всем, что вы купили) и скопируйте HOST, PORT, USERNAME и PASSWORD. На странице «Подключение» есть готовый пример с вашими данными.

3. Шаг 3

   Введите данные в браузер или программу, которую вы настраиваете.

4. Шаг 4

   Подтвердите выход запросом к https://ipinfo.io/json через прокси.

5. Шаг 5

   Из материкового Китая сначала запустите вспомогательную программу на странице «Подключение» и держите её открытой, пока работает прокси.

   • Руководство по вспомогательной программе

Цены и ограничения

Бюджетная линия стоит $1,50 за ГБ, $1,35 за ГБ в пакете 100 ГБ и $1,20 за ГБ при 300 ГБ. Бесплатного пробного периода нет, а минимальная покупка составляет 1 ГБ. Набор доступных локаций меняется ежедневно.

• Источники:
• Факты о продуктах и прайс Proxy302

Частые вопросы

Читайте дальше

Адрес, порт, логин и пароль прокси

Каждый рабочий прокси описывается пятью базовыми полями: протокол, адрес хоста, порт, логин и пароль.

Ошибка 407: требуется авторизация на прокси

Ответ HTTP 407 приходит от прокси-сервера, а не от сайта, который вы пытаетесь открыть.

ERR_PROXY_CONNECTION_FAILED: что проверить

Ошибка ERR_PROXY_CONNECTION_FAILED появляется в Chrome и Edge, когда браузер не может установить соединение с прокси-сервером.

Как проверить прокси: IP, страна, провайдер

Как за 30 секунд проверить IP, страну и провайдера прокси, почему сервисы расходятся в городе и что значит «чистота» IP. С нашей проверкой трёх сервисов.