Как настроить прокси Axios в Node.js (да, даже для HTTPS)

Где-то на Stack Overflow прямо сейчас кто-то уверен, что Axios «тихо ломается» на HTTPS-прокси. Это один из самых часто повторяемых тезисов в туториалах по прокси в Node.js, но он не описывает текущую версию, которую мы тестировали для этого материала. Я поднял локальный стенд с реальными HTTP- и HTTPS-источниками за двумя прокси, и Axios 1.19.0 успешно пропустил HTTPS-запрос через корректный CONNECT, а не обошёл прокси стороной.

Это не значит, что проблемы, о которых говорят пользователи, выдуманы. В старых версиях Axios действительно были баги (см. issue #3384 и issue #4531), а в новых версиях Node появился ещё и отдельный путь работы с proxy-средой, который нужно настраивать аккуратно. В этом гайде разберём, что реально работает в Axios 1.19.0 на сегодня, все способы подключить прокси к запросам, схему ротации через interceptors, которую почти никто не показывает, и полноценную таблицу «ошибка — решение» на случай, если что-то всё-таки пойдёт не так.

Что такое прокси в Axios и зачем он вообще нужен в Node.js?

В контексте Axios прокси — это просто промежуточный сервер между вашим процессом Node и целевым сайтом. Запрос сначала идёт на прокси, потом прокси пересылает его дальше, а сайт видит IP прокси, а не ваш. В этом и весь смысл.

Разработчики используют это по нескольким причинам: чтобы скрапить сайты с лимитами или блокировкой по IP, проверять поведение приложения из другой страны, отправлять трафик через корпоративный выходной узел или просто не светить IP своего сервера в логах целевого ресурса. Официальная конфигурация запросов Axios включает встроенную опцию proxy с полями host, port, protocol и auth — она существует уже много лет, и именно её показывает каждый туториал, включая этот.

Есть нюанс, который обычно упускают: опция proxy ведёт себя по-разному в зависимости от того, обращаетесь ли вы к HTTP- или HTTPS-ресурсу, и от версии Axios. Именно поэтому и появился этот гайд.

Настраиваем Node.js и Axios: быстрый старт

Пропустите этот шаг, если проект у вас уже есть. Если нет — это займёт около двух минут.

mkdir axios-proxy-demo && cd axios-proxy-demo
npm init -y
npm install axios

Добавьте "type": "module" в package.json, если хотите использовать ESM-import’ы (я бы так и сделал — CommonJS require() в примере с прокси уже кажется устаревшим). Текущая LTS-версия Node — v24.18.0, хотя я специально тестировал на v22.22.3, чтобы результаты не зависели от самых свежих особенностей рантайма.

Поместите это в app.js и запустите node app.js:

import axios from 'axios';

const res = await axios.get('https://httpbin.org/ip');
console.log(res.data);

В ответе вы увидите свой реальный IP-адрес. Это ваша базовая точка отсчёта: когда прокси будет работать, тот же запрос должен возвращать уже IP прокси.

Сохраните этот ответ до включения прокси — он пригодится как конкретная база для сравнения со следующим запросом через прокси.

Поддерживает ли Axios HTTPS-прокси на самом деле? Разбираемся без мифов

Короткий ответ: да, в текущем стабильном релизе. Axios 1.19.0 документирует CONNECT-туннелирование для HTTPS-целей через HTTP-прокси. API загрузок npm зафиксировал 117 890 039 скачиваний Axios с 31 июля по 6 августа 2026 года — устаревший, но показательный индикатор масштаба использования библиотеки. Когда вы обращаетесь к HTTPS-URL через прокси, текущий Axios отправляет CONNECT-запрос, чтобы поднять туннель, а TLS-рукопожатие проходит end-to-end с настоящим origin. Я проверил это напрямую: локальный HTTP-прокси, локальный HTTPS-origin с self-signed сертификатом, и счётчик CONNECT на прокси вырос ровно как ожидалось.

Так почему же формулировка вроде «Axios HTTPS proxy broken» всплывает почти в каждом обсуждении? Причин несколько, и все они реальные:

Старые версии Axios. На GitHub часто ссылаются на баги многолетней давности, которые описывают поведение конкретного релиза и конфигурации, но их нельзя автоматически переносить на текущий Axios.
Прокси-серверы без поддержки CONNECT. В такой конфигурации туннель не поднимется, и Axios должен вернуть ошибку; сначала проверьте реальный маршрут и сообщение об ошибке, а уже потом подозревайте обход прокси.
Путаница в том, что делает proxy. Опция proxy — это указание на forward-proxy, а не универсальный переключатель «пускать вообще весь трафик через этот agent при любых условиях».

Chromium сообщал в 2023 году, что более 90% навигаций Chrome на основных платформах использовали HTTPS. Это тоже не свежая глобальная статистика всего веба, но она хорошо объясняет, почему поведение для HTTPS-целей нужно разбирать в центре этого материала. Если вы сидите на старом Axios, сначала воспроизведите проблему на актуальной ветке, прежде чем считать, что исторический баг всё ещё актуален; обязательно проверьте апгрейд в своём приложении до деплоя.

Когда всё же нужен явный Agent

Нативная настройка proxy подходит для одного статического и привычного прокси. Но она быстро начинает мешать, когда вам нужен контроль на уровне отдельных запросов, ротация прокси или SOCKS-поддержка — встроенная опция Axios просто не под это сделана. Здесь и пригодится HttpsProxyAgent, о котором ниже. Думайте о встроенной опции как о решении «достаточно хорошо для одного прокси и одной задачи», а о варианте с agent — как о том, что обычно действительно нужно в продакшене.

Путь через переменные окружения в Node v24 и v22.21+

В новых версиях Node есть встроенный режим работы с proxy через environment, включаемый через NODE_USE_ENV_PROXY=1 или флаг --use-env-proxy. Согласно документации CLI Node, эта возможность появилась в v24.0.0 и была перенесена в v22.21.0 — так что формулировка «Node 22+» технически неверна; речь именно о v22.21.0 и новее внутри этой ветки. Если у вас более ранний патч Node 22, этого флага у вас просто нет.

Текущий Axios уже умеет читать HTTP_PROXY, HTTPS_PROXY и NO_PROXY через зависимость proxy-from-env, так что global-agent для этого сценария не нужен. Если одновременно включён и встроенный env-proxy режим Node, в решении о маршрутизации могут участвовать уже два слоя.

В документации Axios отмечено: на версиях Node, где у agent есть свойство proxyEnv, Axios отдаёт решение Node и не делает собственное разрешение. На практике отсюда следует простое правило — выберите один подход и придерживайтесь его:

Пусть маршрутизацией занимается Node: включите флаг, не задавайте proxy в Axios, и пусть всё делают переменные окружения.
Пусть маршрутизацией занимается Axios: не включайте флаг Node, и дайте Axios самому читать env-переменные.
Полный ручной контроль: явно укажите proxy: false и передайте свой httpsAgent — так вы обходите обе автоматические системы, и именно этот вариант я рекомендую, когда нужна ротация или логика на уровне каждого запроса.

Я отдельно проверил путь на стороне Axios: если задать HTTP_PROXY в окружении дочернего процесса, запрос уйдёт через локальный прокси; если добавить соответствующий NO_PROXY, следующий запрос корректно его обойдёт. Значит, env-путь действительно работает «из коробки» — следить нужно именно за сценарием с двумя одновременно активными режимами.

5 способов подключить прокси к Axios — сравнение

Прежде чем лезть в код, вот общая картина. Я собрал и протестировал каждый из этих вариантов на реальном локальном прокси, а не просто по документации.

Способ	Поддержка HTTPS	Поддержка auth	Управление на уровне запроса	Подходит для ротации	Сложность
Встроенная опция `proxy`	✅ (текущий Axios)	✅	✅	❌	Низкая
Дефолты через `axios.create()`	✅ (текущий Axios)	✅	❌ (на весь instance)	❌	Низкая
Переменные окружения (`HTTP_PROXY`/`HTTPS_PROXY`)	✅	✅	❌	❌	Низкая
`httpsAgent` + `HttpsProxyAgent`	✅	✅	✅	⚠️ (вручную)	Средняя
Request interceptor + пул agent’ов	✅	✅	✅	✅	Средне-высокая

Используйте встроенную опцию для короткого скрипта с одним прокси. Берите axios.create(), если все запросы в модуле должны идти через один и тот же прокси без повторения настроек. Используйте переменные окружения, если инфраструктура уже централизованно управляет маршрутизацией, а вам нужно лишь унаследовать её. Переходите к явному agent, когда встроенной конфигурации уже не хватает, а к interceptor-подходу — в тот момент, когда «контроль» превращается в «ротацию».

Три способа маршрутизации Axios через прокси сходятся к HTTPS-цели

Пошагово: базовая настройка прокси в Axios

Самый простой вариант — использовать встроенный объект proxy прямо в запросе:

import axios from 'axios';

const res = await axios.get('https://httpbin.org/ip', {
  proxy: {
    host: '203.0.113.10',
    port: 8080,
    protocol: 'http',
  },
});

console.log(res.data);

Запустите это, и в ответе вы должны увидеть IP прокси, а не свой собственный. Если тестируете локально на настоящем прокси, это обычно занимает меньше секунды — в отличие от ручной настройки системного proxy только ради одного запроса, которая легко съедает лишние 15 минут.

Сравните ответ с базовой точкой отсчёта. Успешный тест должен показать публичный IP прокси, а не origin-IP, который вы зафиксировали ранее.

Используем `axios.create()` для настроек на весь instance

Если все запросы в конкретном модуле должны идти через один прокси, лучше зашить его в instance, а не повторять конфиг каждый раз:

const client = axios.create({
  proxy: {
    host: '203.0.113.10',
    port: 8080,
  },
  timeout: 15_000,
});

const res = await client.get('https://httpbin.org/ip');

Я проверил, что proxy: false в отдельном запросе чисто отключает дефолты instance — это полезно, если 95% вызовов должны идти через прокси, а несколько штук, например health-check ping, — нет.

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

Если маршрутизацией управляют централизованно — например, в Docker-контейнерах или CI, где ops уже выставляет proxy env vars, — в Axios вообще не нужно ничего настраивать:

export HTTP_PROXY=http://203.0.113.10:8080
export HTTPS_PROXY=http://203.0.113.10:8080
export NO_PROXY=localhost,127.0.0.1

Текущий Axios читает эти переменные без global-agent. Только не забывайте про границу версий Node выше: если включён ещё и NODE_USE_ENV_PROXY, заранее определите, кто именно владеет маршрутизацией, и обязательно проверьте поведение NO_PROXY в реальном рантайме.

Пошагово: настройка HTTPS-прокси через `httpsAgent` — когда нужен реальный контроль

Это тот вариант, который я бы действительно рекомендовал, если вам нужно больше, чем «один прокси навсегда». Установите актуальный пакет agent:

npm install https-proxy-agent

https-proxy-agent 9.1.0 требует Node 20 или новее и сначала отправляет корректный CONNECT на прокси, а уже потом туннелирует через него соединение к цели.

import axios from 'axios';
import { HttpsProxyAgent } from 'https-proxy-agent';

const agent = new HttpsProxyAgent('http://203.0.113.10:8080');

const client = axios.create({
  proxy: false,        // отключаем нативное разрешение Axios, чтобы оно не вмешивалось
  httpsAgent: agent,
  timeout: 15_000,
});

const res = await client.get('https://httpbin.org/ip');
console.log(res.data);

Когда маршрутизацией управляет явный agent, ставьте proxy: false. Так конфигурация остаётся однозначной, и нативный или env-based механизм Axios не спорит с переданным agent’ом.

Добавляем авторизацию на прокси

Учетные данные можно встроить прямо в URL прокси:

const agent = new HttpsProxyAgent('http://myuser:mypassword@203.0.113.10:8080');

Если в пароле есть спецсимволы — чаще всего проблемы создают @, : и # — обязательно percent-encode их перед сборкой URL или формируйте строку через encodeURIComponent() для каждого компонента. Сырой @ в пароле будет воспринят как начало части host, и вы получите ошибку соединения, которая на первый взгляд вообще не похожа на проблему кодирования.

Как использовать SOCKS5-прокси с Axios

SOCKS-прокси несовместимы с HttpsProxyAgent — для этого протокола нужен другой agent:

npm install socks-proxy-agent

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

const agent = new SocksProxyAgent('socks5://myuser:mypass@203.0.113.10:1080');

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

socks-proxy-agent 10.1.0 тоже требует Node 20+. SOCKS5 имеет смысл использовать, когда вы работаете с корпоративными сетями, где доступен только SOCKS-шлюз, или с провайдерами прокси, которые предлагают более гибкую поддержку протоколов, чем обычные HTTP-прокси.

Ротация прокси в Axios через request interceptors

Выбирать случайный прокси прямо в месте вызова нормально для разового скрипта. Но это разваливается, как только вы начинаете делать сотни запросов: нет централизованного учёта мёртвых прокси, нет retry-логики, а код выбора прокси размазывается по всему проекту. Система interceptors в Axios даёт этой логике одно тестируемое место; ни один из пяти конкурирующих туториалов, которые я смотрел в SERP, этот паттерн не использовал.

GET-запросы Axios поочерёдно проходят через три прокси с одним ограниченным retry

Собираем пул прокси

import axios, { AxiosError, InternalAxiosRequestConfig } from 'axios';
import { HttpsProxyAgent } from 'https-proxy-agent';

class ProxyPool {
  private agents: HttpsProxyAgent<string>[];
  private index = 0;

  constructor(proxyUrls: string[]) {
    this.agents = proxyUrls.map((url) => new HttpsProxyAgent(url));
  }

  next(): HttpsProxyAgent<string> {
    const agent = this.agents[this.index];
    this.index = (this.index + 1) % this.agents.length;
    return agent;
  }
}

const pool = new ProxyPool([
  'http://user:pass@proxy1.example.com:8080',
  'http://user:pass@proxy2.example.com:8080',
]);

const client = axios.create({ timeout: 15_000 });

client.interceptors.request.use((config: InternalAxiosRequestConfig) => {
  config.proxy = false;
  config.httpsAgent = pool.next();
  return config;
});

Я прогнал это через два локальных прокси и подтвердил, что запросы идут по очереди — прокси A, потом прокси B, потом снова A. Учтите, что Axios выполняет request interceptors в порядке LIFO, так что если у вас есть другие interceptors (заголовки авторизации, логирование), порядок важнее, чем кажется.

Добавляем response interceptor с защитой от бесконечных retry

Именно здесь большинство самодельных скриптов ротации начинает вести себя неаккуратно. Безусловный retry при любой ошибке и на бесконечном пуле может превратить один сбойный запрос в лавину проблем — особенно для неидемпотентных методов вроде POST, где повтор может продублировать действие, которое вообще не следовало повторять.

type RetryableConfig = InternalAxiosRequestConfig & {
  __proxyRetryCount?: number;
};

client.interceptors.response.use(
  undefined,
  async (error: AxiosError) => {
    const config = error.config as RetryableConfig | undefined;
    if (!config) throw error;

    const method = String(config.method ?? 'get').toUpperCase();
    config.__proxyRetryCount ??= 0;
    if (method !== 'GET' || config.__proxyRetryCount >= 1) throw error;

    config.__proxyRetryCount += 1;
    config.proxy = false;
    config.httpsAgent = pool.next();
    return client.request(config);
  }
);

Я протестировал это на заведомо сломанном прокси и подтвердил, что срабатывает ровно один retry на альтернативном agent’е — без бесконечного цикла и без retry для POST. Именно такая граница и нужна: политика повторов должна честно учитывать, какие запросы можно безопасно повторить, а не быть хаком в духе «просто пробуем снова, пока не заработает».

Отладка проблем с Axios proxy через cURL, 407 и проверку таймаутов

Таблица диагностики ошибок: сопоставляем сбой и решение

Сохраните себе. Это реальные ошибки, которые действительно всплывают в issue Axios и обсуждениях на Stack Overflow, а не гипотетические примеры.

Ошибка / симптом	Вероятная причина	Что делать
`ECONNREFUSED`	Неверный host/port или прокси-сервер не запущен	Проверьте связность через `curl -x http://host:port target-url`, прежде чем менять код Axios
`407 Proxy Authentication Required`	Нет учётных данных или они указаны неверно	Добавьте `auth: { username, password }` в конфиг `proxy` или встроите креды в URL для `HttpsProxyAgent`
`403 Forbidden`	Origin или WAF отклонил запрос или IP прокси	Проверьте политику доступа сайта, авторизацию и частоту запросов; не считайте, что другой заголовок или IP дают право обойти ограничения
В ответе виден ваш реальный IP	`NO_PROXY`, `proxy:false`, явный direct agent или историческая/версийная конфигурация обходят прокси	Разберитесь, какой слой отвечает за маршрутизацию; при необходимости проверьте путь через контролируемую IP-цель и явный agent
`ETIMEDOUT`	Превышен таймаут подключения или ответа	Измерьте, где именно уходит время; увеличивайте timeout только если это оправдано задачей, иначе замените или «остудите» проблемный маршрут
`ECONNRESET` в середине ответа	Прокси, сеть или origin разорвали соединение	Зафиксируйте, на каком хопе всё ломается; повторяйте только безопасные к повтору запросы и с ограниченным числом попыток
`502 Bad Gateway` за Nginx	Неправильно настроен `proxy_pass` в Nginx или timeout Axios не совпадает с Nginx	Проверьте `proxy_connect_timeout` и `proxy_read_timeout` (по умолчанию оба 60s) и согласуйте их с `timeout` в Axios
`ERR_TLS_CERT_ALTNAME_INVALID`	Неправильный тип agent для цели или self-signed сертификат	Убедитесь, что используете подходящий agent для протокола; `rejectUnauthorized: false` допустим только для локального тестирования — никогда не в production

Короткий чек-лист отладки

Если что-то сломалось, а причина неочевидна, пройдите по этому списку по порядку:

Проверьте прокси напрямую через curl -x http://host:port https://your-target.com. Если не работает, ищите проблему в подключении к прокси, авторизации и самой цели, а не в Axios. Если работает, путь через Axios всё равно нужно проверять отдельно.
Убедитесь, какие именно версии Axios и Node у вас запущены, и сравнивайте старые отчёты с тем же релизом и той же конфигурацией, прежде чем применять найденные там «фиксы».
Определите, кто именно делает resolution прокси: нативная конфигурация Axios, env-резолв Axios, встроенный env-proxy режим Node или явный agent. Никогда не давайте одному и тому же запросу больше одного «хозяина».
Проверьте NO_PROXY на случайные совпадения по hostname.
Если используете явный agent, убедитесь, что proxy: false действительно задан, чтобы Axios не попытался обработать маршрут дважды.

Когда лучше вообще не собирать прокси-логику вручную

Всё вышеописанное действительно полезно, если ваша реальная задача — маршрутизировать произвольный трафик: тестировать корпоративную сеть, проверять геоповедение приложения или контролировать исходящий трафик. Но многие приходят к вопросу «как настроить Axios proxy» потому, что на самом деле им нужны данные с сайта, а прокси — лишь средство.

Если это ваш случай, стоит спросить себя: вам правда нужен прокси или всё же нужен scraping API, который возьмёт инфраструктуру на себя? Open API Thunderbit принимает URL и схему и возвращает структурированный JSON — без парсинга сырого HTML, без библиотек для agent’ов и без необходимости вручную поддерживать пул прокси. /extract endpoint обрабатывает страницы с JavaScript, антибот-защиту и CAPTCHA на стороне сервиса, а более лёгкий /distill endpoint просто превращает страницу в чистый Markdown, если вам нужно только это. Есть также MCP-сервер с инструментами вроде thunderbit_extract и thunderbit_suggest_fields, чтобы такие ассистенты, как Claude или Cursor, могли получать структурированные данные прямо в процессе работы без настройки прокси, а ещё CLI для терминала и CI-сценариев.

Вопрос	Самостоятельно: Axios + прокси	Thunderbit API/MCP/CLI
Источник и ротация прокси	Вы управляете сами	Обрабатывается на стороне сервиса
Сложности браузера и доступа	Вы поддерживаете сетевой/браузерный слой	Управляется сервисом в пределах его возможностей
Страницы с JS-рендерингом	Нужен headless browser	`renderMode: full`
Формат вывода	Raw HTML → парсите сами	Структурированный JSON по схеме
Поддержка при изменении сайтов	Вы обновляете парсинг и селекторы	Управляемый слой извлечения снижает часть нагрузки на приложение

Честная формулировка такая: если вам нужно маршрутизировать трафик для тестирования или корпоративной сети — никакой API не заменит Axios и конфиг прокси. Если же результатом должны быть структурированные веб-данные, подход API-first может уменьшить объём кода для прокси, браузера и парсинга, который вы вообще вынуждены поддерживать. На момент получения данных 7 августа 2026 года в документации Thunderbit по rate limits для Free tier было указано 10 запросов в минуту и 2 одновременных запроса. Считайте это временными лимитами API и перепроверяйте страницу перед тем, как полагаться на них в production.

Итоги

Главный вывод здесь идёт вразрез с тем, что пишут многие старые туториалы: текущий Axios в документации и в наших локальных тестах корректно использовал CONNECT-туннелирование для HTTPS-цели. Исторические сбои по-прежнему важны, но их надо рассматривать с учётом версии и конфигурации. Нативная настройка — хороший старт с низкой сложностью; когда нужен контроль на уровне запроса, поддержка SOCKS или ротация, явный HttpsProxyAgent (или SocksProxyAgent) вместе с proxy: false даёт гораздо более ясное владение маршрутом. А если вы ротируете пул в production, request- и response-interceptors дают централизованное и тестируемое место для этой логики — только не забудьте про защиту от циклов и повторяйте лишь те запросы, которые действительно безопасны для повторной отправки.

Сохраните таблицу диагностики выше на случай, когда в 2 часа ночи прокси-конфигурация выдаст криптическую ошибку. А если поймаете себя на том, что тратите больше времени на отладку прокси-обвязки, чем на использование самих данных, возможно, стоит проверить, не решит ли API-first инструмент для извлечения данных вашу задачу быстрее, чем любая инфраструктура.

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

Поддерживает ли Axios HTTPS-прокси нативно?
Да, в текущем Axios для обычного HTTP-прокси: актуальная документация описывает CONNECT-туннелирование для HTTPS-целей, и Axios 1.19.0 успешно прошёл этот сценарий в локальном тесте. В старых релизах и при некоторых конфигурациях прокси действительно были ошибки, поэтому проверяйте точную версию и конкретный прокси, а не делайте вывод, что всё либо всегда работает, либо всегда ломается.

Как ротировать прокси в Axios?
Используйте request interceptor, чтобы перед каждым запросом подставлять другой httpsAgent из пула прокси, и дополняйте это response interceptor’ом, который повторяет неудачные запросы через другой прокси. Ограничьте retry — один повтор и только для идемпотентных методов вроде GET — чтобы случайно не повторить запрос, который повторять нельзя.

Почему Axios-прокси показывает мой реальный IP?
Проверьте, не обошли ли прокси NO_PROXY, proxy:false, явный direct agent или специфичная для деплоя маршрутизация. Зафиксируйте версии Axios и Node и протестируйте прокси отдельно через cURL. Если вам нужен однозначный маршрут на уровне запроса, используйте HttpsProxyAgent вместе с proxy:false и проверьте наблюдаемый IP на контролируемой конечной точке.

Можно ли использовать SOCKS5-прокси с Axios?
Да, через пакет socks-proxy-agent. Создайте экземпляр SocksProxyAgent с вашим SOCKS-URL и передайте его в httpsAgent в конфигурации Axios — только не передавайте одновременно HttpsProxyAgent, потому что это разные протоколы и разные типы agent’ов.

В чём разница между опцией proxy и httpsAgent в Axios?
proxy — это встроенная конфигурация Axios для одного статичного прокси, и в текущих версиях она нормально подходит для простых сценариев. httpsAgent принимает пользовательский Node.js agent — например, HttpsProxyAgent или SocksProxyAgent — и даёт прямой контроль на уровне каждого запроса над маршрутизацией, авторизацией и ротацией, для чего встроенная опция изначально не предназначалась.

Узнать больше

От веб-страницы к таблице

Опиши, что тебе нужно, — AI-агент Thunderbit соберет это и экспортирует в Excel, Google Sheets, Airtable или Notion. Старт бесплатный.

Chrome Store Rating

PRODUCT HUNT#1 Product of the Week