Использование прокси-сервера разработки с приложениями Node.js

На первый взгляд
Цель: Настройка приложений Node.js для использования прокси-сервера разработки
Время: 10 минут
Предварительные требования:Настройка прокси-сервера разработки, Node.js приложения

Маршрутизация запросов Node.js через Dev Proxy зависит от версии Node.js и библиотеки, используемой для выполнения HTTP-запросов. Последние версии Node.js могут направлять собственный API fetch и модули http и https через прокси-сервер, определенный в переменных среды. Для старых версий Node.js и для других библиотек вы настраиваете прокси-сервер в коде или используете global-agent пакет для поддержки прокси-сервера с минимальными изменениями кода.

Независимо от того, какой подход используется, Node.js должен доверять корневому сертификату Dev Proxy, чтобы выполнять HTTPS-запросы через Dev Proxy. Дополнительные сведения см. в разделе Доверие к сертификату прокси-сервера разработки.

Доверять сертификату прокси для разработки

Node.js по умолчанию не использует хранилище сертификатов операционной системы, поэтому он не доверяет корневому сертификату Dev Proxy даже если вы добавили его в доверенные на своем компьютере. Вместо отключения проверки сертификатов добавьте корневой сертификат прокси-сервера разработки в сертификаты, которым доверяет Node.js, с помощью переменной среды NODE_EXTRA_CA_CERTS.

NODE_EXTRA_CA_CERTS требуется сертификат в формате PEM. Пока запущен Dev Proxy, получите маркер API с помощью devproxy api token и скачайте корневой сертификат в формате PEM с помощью API Dev Proxy:

TOKEN=$(devproxy api token)
curl -H "Authorization: Bearer $TOKEN" -o dev-proxy-ca.pem "http://127.0.0.1:8897/proxy/rootCertificate?format=crt"

Если вы используете PowerShell, выполните следующую команду:

$token = devproxy api token
Invoke-WebRequest -Headers @{ Authorization = "Bearer $token" } -OutFile dev-proxy-ca.pem -Uri "http://127.0.0.1:8897/proxy/rootCertificate?format=crt"

Затем укажите для переменной среды NODE_EXTRA_CA_CERTS путь к скачанному файлу при запуске приложения:

NODE_EXTRA_CA_CERTS=./dev-proxy-ca.pem node index.js

Node.js считывает NODE_EXTRA_CA_CERTS только при запуске процесса, поэтому его нельзя задать из кода. Каждая установка Dev Proxy использует собственный корневой сертификат. Если вы повторно создадите сертификат, например с помощью devproxy cert remove и devproxy cert ensure, скачайте его еще раз.

Нативный fetch API для Node.js

Начиная с Node.js версии 24.0.0 и версии 22.21.0 собственный fetch API может использовать прокси-сервер, определенный в переменных среды HTTP_PROXY, HTTPS_PROXY и NO_PROXY. Начиная с Node.js версии 24.5.0 и версии 22.21.0, то же самое относится к модулям http и https. Node.js игнорирует эти переменные, если вы не включите поддержку прокси-сервера, задав переменной среды NODE_USE_ENV_PROXY значение 1 или запустив Node.js с флагом --use-env-proxy.

Вам не нужно изменять код для использования Dev Proxy с нативным fetch API:

(async () => {
  const result = await fetch('https://jsonplaceholder.typicode.com/posts');
  const jsonResult = await result.json();
  console.log(JSON.stringify(jsonResult, null, 2));
})();

При запуске приложения включите поддержку прокси-сервера, укажите Dev Proxy в качестве прокси-сервера и доверяйте корневому сертификату Dev Proxy:

NODE_USE_ENV_PROXY=1 HTTPS_PROXY=http://127.0.0.1:8000 HTTP_PROXY=http://127.0.0.1:8000 NODE_EXTRA_CA_CERTS=./dev-proxy-ca.pem node index.js

В качестве альтернативы используйте флаг --use-env-proxy вместо переменной среды NODE_USE_ENV_PROXY:

HTTPS_PROXY=http://127.0.0.1:8000 HTTP_PROXY=http://127.0.0.1:8000 NODE_EXTRA_CA_CERTS=./dev-proxy-ca.pem node --use-env-proxy index.js

Note

Встроенная поддержка прокси-сервера находится в активной разработке в Node.js. Чтобы проверить, поддерживает ли это ваша версия Node.js, выполните команду node --version. Если вы используете более раннюю версию, используйте undici пакет или global-agent пакет, как описано в следующих разделах.

Использование встроенного fetch API с более старыми версиями Node.js

Если вы используете версию Node.js, которая не поддерживает NODE_USE_ENV_PROXY, используйте EnvHttpProxyAgent из пакета undici, который реализует нативный fetch API в Node.js. EnvHttpProxyAgent считывает прокси-сервер из переменных среды HTTP_PROXY, HTTPS_PROXY и NO_PROXY. Задайте его в качестве глобального диспетчера в начале приложения:

import { EnvHttpProxyAgent, setGlobalDispatcher } from 'undici';
setGlobalDispatcher(new EnvHttpProxyAgent());

(async () => {
  const result = await fetch('https://jsonplaceholder.typicode.com/posts');
  const jsonResult = await result.json();
  console.log(JSON.stringify(jsonResult, null, 2));
})();

При запуске приложения укажите Dev Proxy в качестве прокси-сервера и доверяйте корневому сертификату Dev Proxy:

HTTPS_PROXY=http://127.0.0.1:8000 HTTP_PROXY=http://127.0.0.1:8000 NODE_EXTRA_CA_CERTS=./dev-proxy-ca.pem node index.mjs

global-agent

global-agent — это популярная библиотека, которая предоставляет глобальный агент HTTP/HTTPS для Node.js. Он позволяет указать прокси-сервер с помощью переменных среды. Преимуществом использования global-agent является то, что вам не нужно изменять способ выдачи HTTP-запросов в приложении для использования прокси-сервера разработки.

Ниже приведен пример использования global-agent в приложении Node.js, которое использует node-fetch:

import fetch from 'node-fetch';
import { bootstrap } from 'global-agent';
bootstrap();

(async () => {
  const result = await fetch('https://jsonplaceholder.typicode.com/posts');
  const jsonResult = await result.json();
  console.log(JSON.stringify(jsonResult, null, 2));
})();

Вот как можно использовать global-agent с Node.js и стандартным https модулем:

const https = require('https');
const globalAgent = require('global-agent');
globalAgent.bootstrap();

https.get('https://jsonplaceholder.typicode.com/posts', (resp) => {
  let data = '';
  resp.on('data', (d) => {
    data += d;
  });
  resp.on('end', () => {
    console.log(JSON.parse(data));
  });
  resp.on('error', (err) => {
    console.error(err);
  });
});

При запуске приложения укажите прокси-сервер с помощью переменной среды GLOBAL_AGENT_HTTP_PROXY и доверяйте корневому сертификату прокси-сервера разработки.

NODE_EXTRA_CA_CERTS=./dev-proxy-ca.pem GLOBAL_AGENT_HTTP_PROXY=http://127.0.0.1:8000 node global-node-fetch.mjs

node-fetch

Node-fetch — это популярная библиотека, которая предоставляет fetch реализацию для Node.js. node-fetch не поддерживает указание прокси-сервера с помощью переменных среды. Вместо этого необходимо создать пользовательский агент и передать его методу fetch .

Пример того, как можно использовать node-fetch с Dev Proxy, определив агента с помощью пакета https-proxy-agent.

const fetch = require('node-fetch');
const { HttpsProxyAgent } = require('https-proxy-agent');

(async () => {
  // Create a custom agent pointing to Dev Proxy
  const agent = new HttpsProxyAgent('http://127.0.0.1:8000');
  // Pass the agent to the fetch method
  const result = await fetch('https://jsonplaceholder.typicode.com/posts', { agent });
  const jsonResult = await result.json();
  console.log(JSON.stringify(jsonResult, null, 2));
})();

При запуске приложения доверяйте корневому сертификату прокси-сервера разработки:

NODE_EXTRA_CA_CERTS=./dev-proxy-ca.pem node index.js

Axios

Axios — это другая популярная библиотека для выполнения HTTP-запросов в Node.js. Axios позволяет указать прокси-сервер с помощью переменных среды или указать агент непосредственно в конфигурации запроса.

Использование Axios и Dev Proxy с переменными среды

При использовании прокси-сервера разработки с Axios и указания прокси-сервера с помощью переменных среды вам не нужно изменять код. Все, что необходимо сделать, — задать https_proxy переменную среды, и Axios использует ее для выполнения запросов.

import axios from 'axios';

(async () => {
  const result = await axios.get('https://jsonplaceholder.typicode.com/posts');
  const response = result.data;
  console.log(JSON.stringify(response, null, 2));
})();

https_proxy Укажите переменную среды глобально или при запуске приложения и доверяйте корневому сертификату прокси-сервера разработки.

https_proxy=http://127.0.0.1:8000 NODE_EXTRA_CA_CERTS=./dev-proxy-ca.pem node axios.mjs

Получил

node-fetchАналогично , Got не поддерживает указание прокси-сервера с помощью переменных среды. Вместо этого необходимо создать пользовательский агент и передать его в запрос.

Ниже приведен пример использования Got с прокси-сервером разработки.

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

(async () => {
  // Create a custom agent pointing to Dev Proxy
  const agent = new HttpsProxyAgent('http://127.0.0.1:8000');
  const result = await got('https://jsonplaceholder.typicode.com/posts', {
    // Pass the agent to the request
    agent: {
      https: agent
    }
  }).json();
  console.log(JSON.stringify(result, null, 2));
})();

При запуске приложения доверяйте корневому сертификату прокси-сервера разработки:

NODE_EXTRA_CA_CERTS=./dev-proxy-ca.pem node got.mjs

SuperAgent

SuperAgent не поддерживает указание прокси-сервера с помощью переменных среды. Чтобы использовать прокси для разработки с SuperAgent, необходимо установить плагин superagent-proxy и настроить прокси, используя метод proxy.

const superagent = require('superagent');
require('superagent-proxy')(superagent);

(async () => {
  const result = await superagent
    .get('https://jsonplaceholder.typicode.com/posts')
    .proxy('http://127.0.0.1:8000');
  console.log(JSON.stringify(result.body, null, 2));
})();

При запуске приложения доверяйте корневому сертификату прокси-сервера разработки:

NODE_EXTRA_CA_CERTS=./dev-proxy-ca.pem node superagent.js

Известные проблемы

При использовании прокси-сервера разработки с Node.js могут возникнуть следующие проблемы.

Ошибка: UNABLE_TO_VERIFY_LEAF_SIGNATURE

При использовании прокси-сервера разработки с Node.js возникает ошибка, аналогичная следующим:

/Users/user/my-app/node_modules/node-fetch/lib/index.js:1501
                        reject(new FetchError(`request to ${request.url} failed, reason: ${err.message}`, 'system', err));
                               ^
FetchError: request to https://jsonplaceholder.typicode.com/posts failed, reason: unable to verify the first certificate
    at ClientRequest.<anonymous> (/Users/user/my-app/node_modules/node-fetch/lib/index.js:1501:11)
    at ClientRequest.emit (node:events:518:28)
    at TLSSocket.socketErrorListener (node:_http_client:495:9)
    at TLSSocket.emit (node:events:518:28)
    at emitErrorNT (node:internal/streams/destroy:169:8)
    at emitErrorCloseNT (node:internal/streams/destroy:128:3)
    at process.processTicksAndRejections (node:internal/process/task_queues:82:21) {
  type: 'system',
  errno: 'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
  code: 'UNABLE_TO_VERIFY_LEAF_SIGNATURE'
}

Эта ошибка означает, что Node.js не доверяет корневому сертификату Dev Proxy. Чтобы устранить эту проблему, скачайте корневой сертификат прокси-сервера разработки и задайте для переменной среды NODE_EXTRA_CA_CERTS значение, равное пути к скачанному файлу, при запуске приложения. Дополнительные сведения см. в разделе Доверие к сертификату прокси-сервера разработки.

NODE_EXTRA_CA_CERTS=./dev-proxy-ca.pem node index.js

Warning

Избегайте установки NODE_TLS_REJECT_UNAUTHORIZED в значение 0, чтобы обойти эту ошибку. Он отключает проверку сертификата для всех запросов HTTPS, выполняемых приложением.

См. также

  • Последнее обновление: