企業ネットワークでNode.jsのfetch()を使うとき、プロキシ対応のためだけにhttps-proxy-agentやglobal-agentを入れていた人は多いはず。
Node.js 24（と22.21.0）で追加されたNODE_USE_ENV_PROXYにより、サードパーティなしでHTTP_PROXY/HTTPS_PROXYが効くようになった。
NODE_USE_ENV_PROXY=1でプロキシ設定を
Node.jsのビルトインfetch()はundiciベースだが、ブラウザのfetchと同様にプロキシ環境変数を無視する設計だった。
Node.js 24以降、NODE_USE_ENV_PROXY=1を設定するとfetch()・http.request()・https.request()すべてが環境変数のプロキシ設定を自動で使う。
対応バージョン
| API | 対応バージョン |
|---|---|
fetch() |
v22.21.0 / v24.0.0+ |
http.request() / https.request()
|
v22.21.0 / v24.5.0+ |
使い方
有効化の方法は2つある。
環境変数で有効化
export NODE_USE_ENV_PROXY=1
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1,.internal.com
node app.js
CLIフラグで有効化
node --use-env-proxy app.js
どちらの場合も、アプリケーションコード側の変更は不要。既存のfetch()呼び出しがそのままプロキシ経由になる。
src/client.ts
// コード変更なし。環境変数だけで動く
const res = await fetch("https://api.example.com/data");
const data = await res.json();
デフォルトでは無効。意図しないプロキシ経由の通信を防ぐための設計上の判断。
NO_PROXYの挙動
NO_PROXYにマッチするホストはプロキシをバイパスして直接接続する。
export NO_PROXY=localhost,127.0.0.1,.internal.com,api.partner.com:8443
| 記法 | 意味 |
|---|---|
localhost |
ホスト名完全一致 |
.internal.com |
サブドメイン含む一致 |
api.partner.com:8443 |
ホスト＋ポート一致 |
* |
全プロキシ無効化 |
http.setGlobalProxyFromEnv()
Node.js 24ではプログラマティックに有効化するAPIも追加された。
src/setup-proxy.ts
import http from "node:http";
// process.envのHTTP_PROXY等を読み取ってグローバルに適用
http.setGlobalProxyFromEnv();
これはアプリ起動後に動的にプロキシを切り替えたい場合や、環境変数を自前で組み立ててから適用したいケースで便利。
Node.js 18〜23ではどうしていたか
ビルトインfetch()にプロキシサポートがなかったため、undiciのEnvHttpProxyAgentを直接使う必要があった。
src/legacy-proxy.ts
import { EnvHttpProxyAgent, setGlobalDispatcher } from "undici";
setGlobalDispatcher(new EnvHttpProxyAgent());
// 以降のfetch()がプロキシ経由になる
const res = await fetch("https://api.example.com/data");
EnvHttpProxyAgentはexperimental扱いで、実行時に警告が出る。Node.js 24以降はNODE_USE_ENV_PROXYを使うほうがよい。
従来手法との比較
| 手法 | 追加依存 | fetch対応 | http/https対応 | 備考 |
|---|---|---|---|---|
NODE_USE_ENV_PROXY |
なし | v24.0.0+ | v24.5.0+ | 推奨 |
--use-env-proxy フラグ |
なし | 同上 | 同上 | 環境変数を汚したくない場合 |
undici EnvHttpProxyAgent
|
undici | v18+ | 非対応 | experimental警告あり |
https-proxy-agent |
あり | 非対応 | 対応 | node-fetchやaxios向け |
global-agent |
あり | node-fetch経由 | 対応 | bootstrap()が必要 |