Настройка прокси в Axios: маршрутизация, аутентификация и NO_PROXY

Для Axios в Node.js начинайте с HTTP-адаптера и явного объекта proxy. Учётные данные прокси держите в proxy.auth, проверьте маршрут и только после этого добавляйте переменные окружения или собственные агенты. Эти слои могут изменить соединение: в нашем локальном тесте proxy: false всё равно использовал прокси, когда у собственного агента Node был настроен proxyEnv.

В этом руководстве используются Axios 1.20.0 и Node.js 24.20.0. Его 15 случаев маршрутизации и четыре проверки рецептов являются синтетическими тестами на loopback, а не измерениями внешнего прокси-сервиса. Axios в браузере и fetch-адаптер Axios — это другие пути; опция proxy относится к HTTP-адаптеру Node. См. конфигурацию Axios и зафиксированную версию HTTP-адаптера.

Выполните одну явную проверку прокси

Используйте proxy-check.mjs, package.json и lock-файл вместе. В новом каталоге, с Node 24.20.0 или новее в линейке Node 24:

for file in package.json package-lock.json proxy-check.mjs; do
  curl --fail --silent --show-error \
    "https://ipvolt.com/downloads/axios-proxy-setup/$file" -o "$file" || exit 1
done
npm ci --ignore-scripts --no-audit --no-fund

Пусть ваш менеджер секретов передаст PROXY_HOST, PROXY_PORT, PROXY_USER и PROXY_PASSWORD, затем запустите node proxy-check.mjs. PROXY_HOST — это имя хоста без схемы и учётных данных. PROXY_PROTOCOL по умолчанию равен http; значение https используйте только для TLS-точки прокси, документированной провайдером. Оно описывает соединение с прокси, а не с целевым сервером. Не вводите настоящие пароли в историю командной оболочки или в промпт агента для написания кода.

Скрипт проверки собирает такую конфигурацию из отдельных полей учётных данных:

const proxy = {
  protocol: process.env.PROXY_PROTOCOL || 'http',
  host: process.env.PROXY_HOST,
  port: Number(process.env.PROXY_PORT),
  auth: {
    username: process.env.PROXY_USER,
    password: process.env.PROXY_PASSWORD,
  },
};

Этот фрагмент показывает форму; загружаемый скрипт проверяет свои входные данные и выполняет запрос. Он выбирает adapter: 'http', отключает редиректы, ограничивает ответ 4 КиБ и использует 5-секундный тайм-аут Axios плюс 6-секундный сигнал отмены. Он проверяет, что возвращённый JSON содержит корректный IP-адрес, и печатает только результат, статус и IP либо код ошибки. Он не печатает исходную ошибку Axios и конфигурацию запроса, в которых могут быть учётные данные.

Запуск скрипта по умолчанию отправляет запрос через ваш прокси на сторонний IPv4 JSON-эндпоинт ipify. Этот сервис видит публичный адрес источника запроса. Задайте в CHECK_URL HTTPS-адрес без учётных данных для утверждённого эндпоинта, который возвращает ответ той же формы { "ip": "..." }. Наблюдаемый IP — это одна проверка маршрута; он не подтверждает страну, оператора, классификацию как residential или гарантию производительности. Мы тестировали скрипт на контролируемых локальных ответах, а не на публичном ipify.

Basic-учётные данные, отправленные обычному HTTP-прокси, не шифруются на участке от клиента до прокси только потому, что целевой адрес использует HTTPS. Используйте TLS-точку прокси, если она поддерживается, и не отключайте проверку сертификатов. Лаборатория тестирует HTTP-прокси, туннелирующий к доверенному HTTPS-серверу; TLS-транспорт до самого прокси она не тестирует.

Выберите слой, который отвечает за маршрутизацию

Эти наблюдения получены на зафиксированном стенде с отключёнными флагами запуска, которые включают встроенную поддержку прокси из окружения. «Напрямую» означает, что прокси стенда ничего не получил; «через прокси» означает, что он зафиксировал запрос или CONNECT. Эти наблюдения сохранены в исходных результатах.

При маршрутизации через окружение HTTP_PROXY применяется к HTTP-адресам, а HTTPS_PROXY — к HTTPS-адресам. Схема в значении всё равно описывает прокси: HTTPS_PROXY=http://gateway:port может выбрать HTTP-прокси для HTTPS-адреса. Наследование объясняет руководство по переменным окружения. Существующая матрица NO_PROXY охватывает свои названные клиенты и версии, а не этот эксперимент с Axios.

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

Для встроенного в Node fetch используйте руководство по диспетчеру Undici. Объект proxy Axios и диспетчер fetch — разные интерфейсы.

HTTPS и аутентификация: найдите слой, на котором происходит сбой

HTTP-адаптер Axios 1.20.0 установил туннель CONNECT для HTTPS-адреса лаборатории. Доверенный локальный центр сертификации пропустил запрос; без этого доверия возникла ошибка DEPTH_ZERO_SELF_SIGNED_CERT. В случае с отклонённым сертификатом прокси увидел CONNECT, но HTTPS-сервер не получил запроса приложения. Совет, что Axios всегда нужен отдельный пакет для туннелирования, не описывает эту протестированную версию.

Для учётных данных прокси используйте proxy.auth; auth верхнего уровня в Axios — это аутентификация на целевом сервере. В успешном случае CONNECT сервер стенда не получил заголовок Proxy-Authorization. Прокси получил эти учётные данные на шаге создания туннеля. Это относится к протестированной конфигурации, а не к произвольным перехватывающим прокси или редиректам.

Неверные учётные данные дали статус 407 и код ERR_BAD_REQUEST как в случае простого HTTP, так и в случае HTTPS CONNECT из скрипта проверки. Отклонённый CONNECT дошёл до прокси, но запроса к серверу не было. Исходная ошибка Axios может включать конфигурацию с учётными данными: сохраняйте очищенный код и статус, если он есть, а не логируйте объект целиком.

Зависший HTTP-сервер дал ECONNABORTED при тайм-ауте стенда в 100 мс. Это фиксирует локальную ветку отказа, а не полезный тайм-аут для продакшена или замер задержки. Многоразовый скрипт проверки использует более длинные ограниченные сроки и никогда не повторяет запрос автоматически.

Воспроизведите матрицу маршрутизации

Скачайте lab.mjs рядом со скриптом проверки и зафиксированными файлами пакета, затем выполните:

curl --fail --silent --show-error \
  https://ipvolt.com/downloads/axios-proxy-setup/lab.mjs -o lab.mjs
node lab.mjs local-results.json

В README описаны предварительные условия и случаи. Стенду нужен OpenSSL; он занимает случайные IPv4-порты на loopback, создаёт временный локальный сертификат и использует выдуманные учётные данные. Сначала уберите флаги запуска, включающие встроенную поддержку прокси из окружения; стенд отклоняет их, потому что они меняют его базовое состояние. Установка зависимостей обращается к реестру пакетов; запросы стенда остаются на loopback.

Записано 28 сентября 2026 года на Node 24.20.0, Axios 1.20.0 и macOS arm64: 15 случаев маршрутизации и четыре проверки рецептов пройдены. Проверки охватывают маршрутизацию, аутентификацию, доверенный и недоверенный локальный HTTPS, область действия адаптера, тайм-аут, корректный вывод IP и отклонение неожиданного тела. Они не измеряют набор адресов провайдера, анонимность, географию или пропускную способность и не тестируют SOCKS, Axios в браузере, редиректы и TLS-транспорт до прокси. Перезапускайте стенд после смены Axios, Node, адаптера или агента.

Если нужна диагностическая помощь внутри агента для написания кода, Proxy Toolkit MCP принимает очищенные описания ошибок. Не передавайте в его аргументах учётные данные и приватные URL и проверяйте предложенные изменения ограниченным запросом.

Доступ к прокси ipvolt пока не открыт. Узнайте, когда откроется доступ. Одно письмо, когда откроется доступ. Больше ничего.