Node.js 애플리케이션에서 개발 프록시 사용

한눈에 보기
목표: 개발 프록시를 사용하도록 Node.js 애플리케이션 구성
시간: 10분
필수 구성 요소:개발 프록시, Node.js 애플리케이션 설정

개발자 프록시를 통해 Node.js 요청을 라우팅하는 방법은 Node.js 버전 및 HTTP 요청을 만드는 데 사용하는 라이브러리에 따라 달라집니다. 최근 Node.js 버전은 환경 변수에 정의된 프록시를 통해 네이티브 http API와 fetch 및 https 모듈을 라우팅할 수 있습니다. 이전 Node.js 버전 및 다른 라이브러리의 경우 코드에서 프록시를 구성하거나, global-agent 패키지를 사용해 최소한의 코드 변경으로 프록시 지원을 사용하도록 설정합니다.

어떤 방법을 사용하든 Dev Proxy를 통해 HTTPS 요청을 수행하려면 Node.js가 Dev Proxy 루트 인증서를 신뢰해야 합니다. 자세한 내용은 Dev Proxy 인증서 신뢰를 참조하세요.

개발자 프록시 인증서 신뢰

Node.js는 운영 체제 인증서 저장소를 기본적으로 사용하지 않으므로 머신에서 신뢰한 후에도 Dev Proxy 루트 인증서를 신뢰하지 않습니다. 인증서 유효성 검사를 사용하지 않도록 설정하는 대신 NODE_EXTRA_CA_CERTS 환경 변수를 사용하여 개발자 프록시 루트 인증서를 Node.js가 신뢰하는 인증서 목록에 추가합니다.

NODE_EXTRA_CA_CERTS 에는 PEM 형식의 인증서가 필요합니다. 개발 프록시가 실행되는 동안 devproxy api token를 사용하여 API 토큰을 가져오고, Dev Proxy API를 사용하여 PEM 형식으로 루트 인증서를 다운로드합니다.

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을 사용하여) 다시 다운로드하세요.

네이티브 Node.js 가져오기 API

Node.js v24.0.0 및 v22.21.0부터 네이티브 fetch API는 HTTPS_PROXY, NO_PROXY, HTTP_PROXY 환경 변수에 정의된 프록시를 사용할 수 있습니다. Node.js v24.5.0 및 v22.21.0부터는 동일한 사항이 https 및 http 모듈에도 적용됩니다. NODE_USE_ENV_PROXY 환경 변수를 1로 설정하거나 --use-env-proxy 플래그로 Node.js를 시작하여 프록시 지원을 활성화하지 않는 한, Node.js는 이러한 변수를 무시합니다.

네이티브 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

또는 NODE_USE_ENV_PROXY 플래그를 --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 패키지를 사용합니다.

이전 Node.js 버전에서 네이티브 페치 API 사용

NODE_USE_ENV_PROXY를 지원하지 않는 Node.js 버전을 사용하는 경우, Node.js의 기본 EnvHttpProxyAgent API를 구현하는 undici 패키지의 fetch를 사용하세요. EnvHttpProxyAgent는 HTTPS_PROXY, NO_PROXY, HTTP_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 는 Node.js 전역 HTTP/HTTPS 에이전트를 제공하는 인기 있는 라이브러리입니다. 환경 변수를 사용하여 프록시를 지정할 수 있습니다. 사용 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));
})();

Node.js 표준 global-agent 모듈과 함께 사용할 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 지정하고 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 는 Node.js 구현을 fetch 제공하는 인기 있는 라이브러리입니다. node-fetch 는 환경 변수를 사용하여 프록시를 지정하는 것을 지원하지 않습니다. 대신 사용자 지정 에이전트를 만들어 메서드에 fetch 전달해야 합니다.

다음은 node-fetch 패키지를 사용하여 에이전트를 정의하고, 개발자 프록시와 함께 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));
})();

앱을 시작할 때 Dev Proxy 루트 인증서를 신뢰:

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

Axios

Axios 는 Node.js HTTP 요청을 만들기 위한 또 다른 인기 있는 라이브러리입니다. Axios를 사용하면 환경 변수를 사용하여 프록시를 지정하거나 요청 구성에서 에이전트를 직접 지정할 수 있습니다.

환경 변수와 함께 Axios 및 개발자 프록시 사용

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 루트 인증서를 신뢰하지 않음을 의미합니다. 이 문제를 해결하려면 Dev Proxy 루트 인증서를 다운로드하고 앱을 시작할 때 다운로드한 파일의 경로로 NODE_EXTRA_CA_CERTS 환경 변수를 설정합니다. 자세한 내용은 Dev Proxy 인증서를 신뢰하기를 참조하세요.

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

Warning

이 오류를 피하기 위해 0을(를) NODE_TLS_REJECT_UNAUTHORIZED(으)로 설정하지 마십시오. 앱이 만드는 모든 HTTPS 요청에 대해 인증서 유효성 검사를 사용하지 않도록 설정합니다.

참고하십시오

Docker 컨테이너에서 Node.js 애플리케이션과 함께 개발 프록시 사용 - Docker 설정
JavaScript Azure Functions에서 개발 프록시 사용 - Azure Functions
용어집 - 개발자 프록시 용어

피드백

이 페이지가 도움이 되었나요?

2026-11-05 에 마지막으로 업데이트됨