Użyj proxy deweloperskiego z aplikacjami Node.js

Na pierwszy rzut oka
Celem: Konfigurowanie aplikacji Node.js do korzystania z usługi Dev Proxy
Czas: 10 minut
Wymagania wstępne:Konfigurowanie serwera proxy dev, Node.js aplikacji

Sposób kierowania żądań Node.js za pośrednictwem Dev Proxy zależy od wersji Node.js i biblioteki używanej do tworzenia żądań HTTP. Najnowsze wersje Node.js mogą kierować natywny interfejs API fetch oraz moduły http i https przez serwer proxy zdefiniowany w zmiennych środowiskowych. W przypadku starszych wersji Node.js i innych bibliotek należy skonfigurować serwer proxy w kodzie lub użyć pakietu global-agent, aby włączyć obsługę serwera proxy z minimalnymi zmianami kodu.

Niezależnie od używanego podejścia Node.js musi ufać certyfikatowi głównemu Dev Proxy, aby wysyłać żądania HTTPS za pośrednictwem Dev Proxy. Aby uzyskać więcej informacji, zobacz Zaufaj certyfikatowi Dev Proxy.

Zaufaj certyfikatowi proxy deweloperskiemu

Node.js domyślnie nie używa magazynu certyfikatów systemu operacyjnego, dlatego nie ufa certyfikatowi głównemu Dev Proxy nawet po obdarzeniu go zaufaniem na tej maszynie. Zamiast wyłączać weryfikację certyfikatu, dodaj główny certyfikat Dev Proxy do certyfikatów, którym Node.js ufa, przy użyciu zmiennej środowiskowej NODE_EXTRA_CA_CERTS.

NODE_EXTRA_CA_CERTS wymaga certyfikatu w formacie PEM. Gdy Dev Proxy jest uruchomiony, pobierz token interfejsu API przy użyciu polecenia devproxy api token, a następnie pobierz certyfikat główny w formacie PEM przy użyciu interfejsu 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"

Jeśli używasz programu PowerShell, uruchom polecenie:

$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"

Następnie ustaw zmienną środowiskową NODE_EXTRA_CA_CERTS tak, aby wskazywała na pobrany plik podczas uruchamiania aplikacji:

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

Node.js odczytuje NODE_EXTRA_CA_CERTS tylko po uruchomieniu procesu, więc nie można ustawić go z poziomu kodu. Każda instalacja Dev Proxy używa własnego certyfikatu głównego. Jeśli ponownie utworzysz certyfikat, na przykład za pomocą polecenia devproxy cert remove i devproxy cert ensure, pobierz go ponownie.

Natywne API fetch dla Node.js

Począwszy od Node.js w wersjach 24.0.0 i 22.21.0 natywny interfejs API fetch może używać serwera proxy zdefiniowanego w zmiennych środowiskowych HTTP_PROXY, HTTPS_PROXY i NO_PROXY. Począwszy od Node.js w wersjach 24.5.0 i 22.21.0, to samo dotyczy również modułów http i https. Node.js ignoruje te zmienne, chyba że włączono obsługę serwera proxy przez ustawienie NODE_USE_ENV_PROXY zmiennej środowiskowej na 1 lub przez uruchomienie Node.js z flagą --use-env-proxy .

Nie musisz zmieniać kodu, aby używać serwera proxy deweloperskiego z natywnym fetch interfejsem API:

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

Podczas uruchamiania aplikacji włącz obsługę serwera proxy, określ Dev Proxy jako serwer proxy i zaufaj certyfikatowi głównemu 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

Alternatywnie użyj flagi --use-env-proxy zamiast zmiennej środowiskowej 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

Wbudowana obsługa serwera proxy jest w fazie aktywnego rozwoju w Node.js. Aby sprawdzić, czy Twoja wersja Node.js to obsługuje, uruchom polecenie node --version. Jeśli używasz starszej wersji, użyj undici pakietu lub global-agent pakietu zgodnie z opisem w poniższych sekcjach.

Używanie natywnego interfejsu API pobierania ze starszymi wersjami Node.js

Jeśli używasz wersji Node.js, która nie obsługuje NODE_USE_ENV_PROXY, użyj elementu EnvHttpProxyAgent z pakietu undici, który implementuje natywny interfejs API fetch w Node.js. EnvHttpProxyAgent odczytuje serwer proxy ze zmiennych środowiskowych HTTP_PROXY, HTTPS_PROXY i NO_PROXY. Ustaw go jako globalny dispatcher na początku aplikacji:

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));
})();

Podczas uruchamiania aplikacji określ Dev Proxy jako serwer proxy i zaufaj certyfikatowi głównemu 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 to popularna biblioteka, która udostępnia globalnego agenta HTTP/HTTPS dla Node.js. Umożliwia określenie serwera proxy przy użyciu zmiennych środowiskowych. Zaletą użycia global-agent jest to, że nie trzeba zmieniać sposobu wystawiania żądań HTTP w aplikacji w celu korzystania z serwera proxy deweloperskiego.

Oto przykład, jak można użyć global-agent w aplikacji Node.js, która korzysta z 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));
})();

Poniżej pokazano, jak używać razem z Node.js i standardowym modułem :

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);
  });
});

Podczas uruchamiania aplikacji określ serwer proxy przy użyciu zmiennej środowiskowej GLOBAL_AGENT_HTTP_PROXY i zaufaj głównemu certyfikatowi Dev 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 to popularna biblioteka udostępniająca implementację fetch Node.js. node-fetch nie obsługuje określania serwera proxy przy użyciu zmiennych środowiskowych. Zamiast tego należy utworzyć agenta niestandardowego i przekazać go do metody fetch.

Oto przykład, jak można użyć node-fetch z Dev Proxy, definiując agenta przy użyciu pakietu 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));
})();

Podczas uruchamiania aplikacji ufaj certyfikatowi głównemu Dev Proxy:

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

Axios

Axios to kolejna popularna biblioteka do tworzenia żądań HTTP w Node.js. Axios umożliwia określenie serwera proxy przy użyciu zmiennych środowiskowych lub określenie agenta bezpośrednio w konfiguracji żądania.

Używanie biblioteki Axios i Dev Proxy z zmiennymi środowiskowymi

Jeśli używasz serwera proxy deweloperskiego z axiosem i określasz serwer proxy przy użyciu zmiennych środowiskowych, nie musisz zmieniać kodu. Wszystko, co musisz zrobić, to ustawić zmienną https_proxy środowiskową, a axios używa go do tworzenia żądań.

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));
})();

Ustaw zmienną https_proxy środowiskową globalnie lub podczas uruchamiania aplikacji i zaufaj certyfikatowi głównemu Dev Proxy.

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

Dostał

Podobnie jak node-fetch, Got nie obsługuje określania serwera proxy przy użyciu zmiennych środowiskowych. Zamiast tego należy utworzyć agenta niestandardowego i przekazać go do żądania.

Oto przykład, jak można użyć Got z Dev Proxy:

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));
})();

Podczas uruchamiania aplikacji ufaj głównemu certyfikatowi Dev Proxy:

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

SuperAgent

SuperAgent nie obsługuje określania serwera proxy przy użyciu zmiennych środowiskowych. Aby używać Dev Proxy z SuperAgent, należy zainstalować wtyczkę superagent-proxy i skonfigurować proxy przy użyciu metody 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));
})();

Podczas uruchamiania aplikacji ufaj certyfikatowi głównemu Dev Proxy:

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

Znane problemy

W przypadku korzystania z serwera proxy deweloperskiego z Node.js mogą wystąpić następujące problemy.

Błąd UNABLE_TO_VERIFY_LEAF_SIGNATURE

W przypadku korzystania z serwera proxy deweloperskiego z Node.js występuje błąd podobny do następującego:

/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'
}

Ten błąd oznacza, że Node.js nie ufa certyfikatowi głównemu Dev Proxy. Aby rozwiązać ten problem, pobierz certyfikat główny Dev Proxy i ustaw zmienną środowiskową NODE_EXTRA_CA_CERTS na ścieżkę pobranego pliku podczas uruchamiania aplikacji. Aby uzyskać więcej informacji, zobacz Zaufaj certyfikatowi Dev Proxy.

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

Warning

Unikaj ustawiania NODE_TLS_REJECT_UNAUTHORIZED na 0, aby obejść ten błąd. Wyłącza walidację certyfikatu dla wszystkich żądań HTTPS, które wykonuje aplikacja.

Zobacz także

  • Ostatnia aktualizacja o