Node.js アプリケーションで Dev Proxy を使用する

概要
目標： 開発プロキシを使用するように Node.js アプリケーションを構成する
時間: 10 分
前提条件:開発プロキシ、Node.js アプリケーションを設定する

Node.js リクエストを Dev Proxy 経由でルーティングする方法は、Node.js のバージョンと、HTTP リクエストを行うために使用するライブラリによって異なります。最近の Node.js バージョンでは、環境変数で定義されたプロキシを介してネイティブ fetch API と http および https モジュールをルーティングできます。古い Node.js バージョンとその他のライブラリの場合は、コードでプロキシを構成するか、global-agent パッケージを使用して、最小限のコード変更でプロキシのサポートを有効にできます。

どちらの方法を使用する場合でも、Node.js は開発プロキシルート証明書を信頼して、開発プロキシ経由で HTTPS 要求を行う必要があります。詳細については、「開発プロキシ証明書を信頼する」を参照してください。

開発プロキシ証明書を信頼する

Node.js では、既定ではオペレーティングシステム証明書ストアが使用されないため、コンピューター上で信頼した後でも Dev Proxy ルート証明書は信頼されません。証明書の検証を無効にする代わりに、NODE_EXTRA_CA_CERTS 環境変数を使用して、Node.js が信頼する証明書に Dev Proxy ルート証明書を追加します。

NODE_EXTRA_CA_CERTS には PEM 形式の証明書が必要です。 Dev Proxy の実行中に、 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 は、HTTP_PROXY、HTTPS_PROXY、および NO_PROXY 環境変数で定義されたプロキシを使用できます。 Node.js v24.5.0 および v22.21.0 以降、http モジュールと https モジュールにも同じことが適用されます。 Node.js は、 NODE_USE_ENV_PROXY 環境変数を 1 に設定するか、 --use-env-proxy フラグで 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

または、--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 パッケージを使用します。

古い Node.js バージョンでネイティブフェッチ API を使用する

NODE_USE_ENV_PROXYをサポートしていない Node.js バージョンを使用する場合は、Node.jsでネイティブ EnvHttpProxyAgent API を実装するundici パッケージのfetchを使用します。 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 は、Node.js用のグローバル HTTP/HTTPS エージェントを提供する一般的なライブラリです。これにより、環境変数を使用してプロキシを指定できます。 global-agentを使用する利点は、Dev Proxy を使用するためにアプリケーションで 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 は、Node.js 向けの fetch の実装を提供する一般的なライブラリです。 node-fetch では、環境変数を使用したプロキシの指定はサポートされていません。代わりに、カスタムエージェントを作成し、 fetch メソッドに渡す必要があります。

https-proxy-agent パッケージを使用してエージェントを定義することで、開発プロキシで node-fetch を使用する方法の例を次に示します。

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 要求を行うもう 1 つの一般的なライブラリです。 Axios を使用すると、環境変数を使用してプロキシを指定したり、要求構成でエージェントを直接指定したりできます。

環境変数で Axios と Dev Proxy を使用する

Axios で Dev Proxy を使用し、環境変数を使用してプロキシを指定する場合は、コードを変更する必要はありません。必要なのは、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 環境変数を指定し、Dev 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));
})();

アプリの起動時に、Dev Proxy ルート証明書を信頼してください。

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

アプリの起動時に、Dev Proxy ルート証明書を信頼してください。

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

既知の問題

Node.jsでDev Proxyを使用すると、次の問題が発生する可能性があります。

`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 環境変数をダウンロードしたファイルのパスに設定します。詳細については、「Dev Proxy 証明書を信頼する」を参照してください。

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

Warning

このエラーを回避するには、 NODE_TLS_REJECT_UNAUTHORIZED を 0 に設定しないでください。アプリが行うすべての HTTPS 要求に対する証明書の検証が無効になります。

こちらも参照ください

Docker コンテナー内の Node.js アプリケーションで開発プロキシを使用する - Docker セットアップ
JavaScript Azure Functions で開発プロキシを使用する - Azure Functions
用語集 - 開発プロキシの用語

フィードバック

このページはお役に立ちましたか?

最終更新: 2026-11-05