Usar o Dev Proxy com aplicativos Node.js

Visão geral
Objetivo: Configurar aplicativos Node.js para usar o Proxy de Desenvolvimento
Tempo: 10 minutos
Pré-requisitos:Configurar o Proxy de Desenvolvimento, Node.js aplicativo

A forma como você roteia Node.js solicitações por meio do Proxy de Desenvolvimento depende da sua versão Node.js e da biblioteca que você usa para fazer solicitações HTTP. Versões recentes do Node.js podem rotear a API nativa fetch e os módulos http e https por meio de um proxy definido em variáveis de ambiente. Para versões mais antigas do Node.js e para outras bibliotecas, configure o proxy em seu código ou use o pacote global-agent para habilitar o suporte a proxy com alterações mínimas no código.

Seja qual for a abordagem usada, Node.js deve confiar no certificado raiz do Dev Proxy para fazer solicitações HTTPS por meio do Dev Proxy. Para obter mais informações, consulte Confiar no certificado do Dev Proxy.

Confie no certificado do Proxy de Dev

Node.js não usa o repositório de certificados do sistema operacional por padrão, portanto, ele não confia no certificado raiz do Dev Proxy mesmo depois que você confia nele em seu computador. Em vez de desabilitar a validação do certificado, adicione o certificado raiz do Dev Proxy aos certificados em que o Node.js confia usando a variável de ambiente NODE_EXTRA_CA_CERTS.

NODE_EXTRA_CA_CERTS requer um certificado no formato PEM. Enquanto o Dev Proxy estiver em execução, obtenha o token de API usando devproxy api tokene baixe o certificado raiz no formato PEM usando a Dev Proxy API:

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

Se você usar o PowerShell, execute:

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

Em seguida, aponte a variável de ambiente NODE_EXTRA_CA_CERTS para o arquivo baixado ao iniciar seu aplicativo:

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

Node.js lê NODE_EXTRA_CA_CERTS somente quando o processo é iniciado, portanto, você não pode defini-lo no seu código. Cada instalação do Dev Proxy usa seu próprio certificado raiz. Se você recriar o certificado, por exemplo, usando devproxy cert remove e devproxy cert ensure, baixe-o novamente.

API fetch nativa do Node.js

Começando com Node.js v24.0.0 e v22.21.0, a API nativa fetch pode usar o proxy definido nas variáveis de ambiente HTTP_PROXY, NO_PROXY e HTTPS_PROXY. Começando com Node.js v24.5.0 e v22.21.0, o mesmo se aplica aos módulos https e http. Node.js ignora essas variáveis, a menos que você habilite o suporte a proxy definindo a NODE_USE_ENV_PROXY variável de ambiente para 1 ou iniciando Node.js com o --use-env-proxy sinalizador.

Você não precisa alterar seu código para usar o Dev Proxy com a API nativa fetch:

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

Ao iniciar seu aplicativo, habilite o suporte a proxy, especifique o Dev Proxy como o proxy e confie no certificado raiz do 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

Como alternativa, use a --use-env-proxy flag em vez da variável de ambiente 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

O suporte integrado a proxy está em desenvolvimento ativo no Node.js. Para verificar se a versão do Node.js dá suporte a ela, execute node --version. Se você usar uma versão mais antiga, use o undici pacote ou o global-agent pacote, conforme descrito nas seções a seguir.

Usar a API fetch nativa com versões mais antigas do Node.js

Se você usar uma versão do Node.js que não dá suporte a NODE_USE_ENV_PROXY, use o EnvHttpProxyAgent do pacote undici, que implementa a API nativa fetch em Node.js. EnvHttpProxyAgent lê o proxy das variáveis de ambiente HTTP_PROXY, HTTPS_PROXY e NO_PROXY. Defina-o como o dispatcher global no início do aplicativo:

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

Ao iniciar seu aplicativo, especifique o Dev Proxy como o proxy e confie no certificado raiz do 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 é uma biblioteca popular que fornece um agente HTTP/HTTPS global para Node.js. Ele permite que você especifique o proxy usando variáveis de ambiente. A vantagem de usar global-agent é que você não precisa alterar a forma como emite solicitações HTTP em seu aplicativo para usar o Dev Proxy.

Aqui está um exemplo de como você pode usar global-agent em um aplicativo Node.js que usa 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));
})();

Veja como você pode usar global-agent com o Node.js e o módulo padrão 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);
  });
});

Ao iniciar seu aplicativo, especifique o proxy usando a GLOBAL_AGENT_HTTP_PROXY variável de ambiente e confie no certificado raiz do Proxy de Desenvolvimento.

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 é uma biblioteca popular que fornece uma fetch implementação para Node.js. node-fetch não dá suporte à especificação do proxy usando variáveis de ambiente. Em vez disso, você precisa criar um agente personalizado e passá-lo para o método fetch.

Aqui está um exemplo de como você pode usar node-fetch com o Dev Proxy definindo um agente usando o https-proxy-agent pacote.

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

Ao iniciar seu aplicativo, confie no certificado raiz do Proxy de Desenvolvimento:

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

Axios

Axios é outra biblioteca popular para fazer solicitações HTTP em Node.js. O Axios permite especificar o proxy usando variáveis de ambiente ou especificar o agente diretamente na configuração da solicitação.

Usar Axios e Dev Proxy com variáveis de ambiente

Quando você usa o Dev Proxy com Axios e especifica o proxy usando variáveis de ambiente, você não precisa alterar seu código. Tudo o que você precisa fazer é definir a variável de ambiente https_proxy e o Axios a utiliza para fazer solicitações.

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

Especifique a https_proxy variável de ambiente globalmente ou ao iniciar seu aplicativo e confie no certificado raiz do Dev Proxy.

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

Obtido

Semelhante ao node-fetch, Got não suporta a especificação do proxy usando variáveis de ambiente. Em vez disso, você precisa criar um agente personalizado e passá-lo para a solicitação.

Aqui está um exemplo de como você pode usar o Got com 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));
})();

Ao iniciar seu aplicativo, confie no certificado raiz do Proxy de Desenvolvimento:

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

SuperAgent

SuperAgent não dá suporte à especificação do proxy usando variáveis de ambiente. Para usar o Dev Proxy com o SuperAgent, você precisa instalar o superagent-proxy plug-in e configurar o proxy usando o método 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));
})();

Ao iniciar seu aplicativo, confie no certificado raiz do Proxy de Desenvolvimento:

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

Problemas conhecidos

Ao usar o Dev Proxy com Node.js, você pode encontrar os seguintes problemas.

UNABLE_TO_VERIFY_LEAF_SIGNATURE erro

Ao usar o Dev Proxy com Node.js, você recebe um erro semelhante a:

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

Esse erro significa que Node.js não confia no certificado raiz do Proxy de Desenvolvimento. Para corrigir esse problema, baixe o certificado raiz do Dev Proxy e defina a variável de ambiente NODE_EXTRA_CA_CERTS com o caminho do arquivo baixado ao iniciar seu aplicativo. Para obter mais informações, consulte Confiar no certificado do Dev Proxy.

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

Warning

Evite definir NODE_TLS_REJECT_UNAUTHORIZED como 0 para contornar esse erro. Ele desabilita a validação de certificado para todas as solicitações HTTPS que seu aplicativo faz.

Consulte também

  • Última atualização em