Node.jsのprocess.envとは？使い方・特徴・活用方法・NODE_ENVでの環境切り替えを徹底解説！

Node.jsで開発をしていると、必ず登場するのがprocess.envです。

process.envはアプリケーションの中でパスワードやAPIキーなどの機密情報を扱ったり、開発環境と本番環境で挙動を切り替えたりするときに利用されます。

ただ、「なんとなく使っているけど仕組みはよく分かっていない…」という方も多いのではないでしょうか。私自身も最初はprocess.envを漠然と使っていましたが、調べていくうちに環境変数の正体や開発環境と本番環境の切り替え方法を理解できるようになりました。

さらに、Reactといったフロントエンドのフレームワークではprocess.envに特有のルール（例: REACT_APP_プレフィックスが必要）もあり、これを押さえておくと環境ごとの切り替えやデバッグがぐっとスムーズになります。

この記事では、『環境変数とprocess.env』について、以下の内容をサンプルコードを用いて、わかりやすく解説します。

• そもそも「環境変数」とは？
  • 現在の環境変数の一覧を確認するコマンド（Windows）
    • コマンドプロンプト（cmd）の場合
    • PowerShellの場合
  • 現在の環境変数の一覧を確認するコマンド（MacやLinux）
    • envコマンド
    • printenvコマンド
    • exportコマンド（bash系シェル）
• process.envとは？
  • process.envの特徴
  • process.envの主な用途
• process.envの使い方
  • 環境変数を一覧表示する
  • 特定の環境変数を参照する
  • 実行時に環境変数を設定する
  • 事前に環境変数を設定する
• process.env.NODE_ENVとは？
  • process.env.NODE_ENVの自動設定
• Reactでの環境変数のルール

そもそも「環境変数」とは？

環境変数（environment variable）は、OS（オペレーティングシステム）が提供するプロセス間で共有できる設定情報です。

OS上で動作するプログラム（プロセス）は、この環境変数を通じて共通の情報を参照できます。言い換えると、システムやアプリケーションが動作する際に参照するグローバル変数のようなものです。

たとえば以下のような情報が環境変数として保存されています。

• 現在のユーザー名
• システムが利用する一時ファイルの保存先
• 実行中のプログラムに渡す設定値（例：NODE_ENV=production）

現在の環境変数の一覧を確認するコマンド（Windows）

Windowsでも環境変数を簡単に確認することができます。ここではコマンドプロンプト（cmd）とPowerShellの2種類の方法を紹介します。

コマンドプロンプト（cmd）の場合

コマンドプロンプト（cmd）の場合、以下のコマンドを実行します。

set

実行すると、以下に示すように現在の環境変数の一覧が表示されます（以下の実行結果では一部だけ抜粋しています）。

C:\Users\user01>set
ALLUSERSPROFILE=C:\ProgramData
APPDATA=C:\Users\Taro\AppData\Roaming
CommonProgramFiles=C:\Program Files\Common Files
USERNAME=user01
USERPROFILE=C:\Users\user01

PowerShellの場合

PowerShellの場合、環境変数はEnv:ドライブを通じて管理されているため、以下のコマンドで一覧を取得できます。

Get-ChildItem Env:

実行すると、以下に示すように現在の環境変数の一覧が表示されます（以下の実行結果では一部だけ抜粋しています）。

PS C:\Users\user01> Get-ChildItem Env:

Name                           Value
----                           -----
ALLUSERSPROFILE                C:\ProgramData
APPDATA                        C:\Users\Taro\AppData\Roaming
CommonProgramFiles             C:\Program Files\Common Files
USERNAME                       user01
USERPROFILE                    C:\Users\user01

現在の環境変数の一覧を確認するコマンド（MacやLinux）

MacやLinuxでも、ターミナルから簡単に環境変数を確認できます。ここでは代表的なコマンドを紹介します。

envコマンド

もっとも一般的なのは、以下のコマンドです。

env

実行すると、以下に示すように現在の環境変数の一覧が表示されます（以下の実行結果では一部だけ抜粋しています）。

user01@Ubuntu:~/work$ env
SHELL=/bin/bash
HOME=/home/user01
LANG=C.UTF-8
USER=user01

printenvコマンド

envコマンドとほぼ同じ結果を返すコマンドにprintenvがあります。

printenv

実行すると、以下に示すように現在の環境変数の一覧が表示されます（以下の実行結果では一部だけ抜粋しています）。

user01@Ubuntu:~/work$ printenv
SHELL=/bin/bash
HOME=/home/user01
LANG=C.UTF-8
USER=user01

特定の環境変数だけ確認したい場合は、以下に示すように変数名を指定します。

user01@Ubuntu:~/work$ printenv HOME
/home/user01

exportコマンド（bash系シェル）

bashやzshなどを利用している場合、以下のように入力しても確認できます。

export

現在の環境変数の一覧が表示されますが、フォーマットがdeclare -xの形で出力されるのが特徴です。

user01@Ubuntu:~/work$ export
declare -x HOME="/home/user01"
declare -x LANG="C.UTF-8"
declare -x SHELL="/bin/bash"
declare -x USER="user01"

process.envとは？

環境変数はOSレベルで管理されていますが、Node.jsアプリケーションからも簡単に確認することができます。そのために使うのがprocess.envというオブジェクトです。

process.envは、Node.jsが提供している環境変数を格納する特別なオブジェクトです。Node.jsアプリケーションが起動すると、OSに定義されている環境変数が自動的にこのオブジェクトに読み込まれ、アプリケーションから参照できるようになります。

イメージ的には、Node.jsアプリケーションとOSの橋渡しをするオブジェクトと考えるとわかりやすいです。このオブジェクトにキーと値が詰まっていて、アプリケーションから必要に応じて取り出して使うことができます。

process.envの使い方

process.envを活用すれば、アプリケーションを環境に応じて柔軟に切り替えることができます。ここでは、process.envの使い方について説明します。

環境変数を一覧表示する

まずはシンプルな例です。index.jsというファイルを作り、次のコードを書きます。

// index.js
console.log(process.env);

このスクリプトを実行すると、現在の環境変数がすべてオブジェクト形式で表示されます。

$ node index.js
{
  USER: 'user01',
  HOME: '/home/user01',
  SHELL: '/bin/bash',
  LANG: 'C.UTF-8',
  ...
}

これは、MacやLinuxでenvコマンドを実行した結果、WindowsでsetやGet-ChildItem Env:を実行した結果とほぼ同じです。

特定の環境変数を参照する

すべての一覧を表示するのではなく、特定の環境変数を参照したい場合はプロパティ名を指定します。

// index.js
console.log(process.env.USER);  // ユーザー名
console.log(process.env.HOME);  // HOMEの内容

実行時に環境変数を設定する

Node.jsアプリケーションを起動するとき、コマンドの前に環境変数を指定することで「その実行中だけ有効な環境変数」を設定できます。

ただし、使うシェル（bash / コマンドプロンプト / PowerShell）によって書き方が違うので注意してください。

Linux / macOS（bash, zshなど）の場合

PORT=3000 NODE_ENV=development node index.js

このように、実行コマンドの前に変数を付けることで、実行中だけ有効な環境変数を設定できます。上記のコマンドでは、PORTとNODE_ENVを一時的に設定して、そのままnode index.jsを実行しています。

コマンドプロントの場合

set PORT=3000 && set NODE_ENV=development && node index.js

コマンドプロントの場合には、setで変数を定義し、&&でつなげます。

PowerShell

$env:PORT="3000"; $env:NODE_ENV="development"; node index.js

PowerShellの場合には、setではなく$env:プレフィックスを使います。

事前に環境変数を設定する

一時的にコマンドと一緒に書くのではなく、あらかじめ設定してから実行することもできます。

ただし、使うシェル（bash / コマンドプロンプト / PowerShell）によって書き方が違うので注意してください。

Linux / macOS（bash, zshなど）の場合

$ export PORT=3000
$ node index.js

exportで設定した環境変数は、その設定はターミナルを閉じるまで有効です。

コマンドプロントの場合

C:\Users\user01>set PORT=5000
C:\Users\user01>node index.js

コマンドプロントの場合には、setコマンドで環境変数を設定します。その設定はターミナルを閉じるまで有効です。

PowerShell

PS C:\Users\user01> $env:PORT=5000
PS C:\Users\user01> node index.js

PowerShellの場合には、$env:を使います。その設定はターミナルを閉じるまで有効です。

process.env.NODE_ENVとは？

process.env.NODE_ENVは、Node.jsやフロントエンドのビルドツールなどでアプリケーションの実行環境を判定するための特別な環境変数です。一般的には以下の3つの値で使い分けられます。

• development（開発環境）
  • ローカルでの開発時に利用。詳細なログを出力したり、ホットリロードを有効にしたりする。
• test（テスト環境）
  • 自動テストを実行するときに利用。テスト専用の設定やモックを使うことが多い。
• production（本番環境）
  • 公開するアプリケーションの実行環境。不要なログを削除したり、最適化を有効にする。

例えば次のようにコードを書いたとします。

if (process.env.NODE_ENV === "development") {
  console.log("デバッグログ: アプリが開発モードで起動しました");
}

ローカル開発環境でNODE_ENV=developmentを指定して実行するとログが表示されますが、本番環境でNODE_ENV=productionに設定して実行すればログは出力されません。

process.env.NODE_ENVの自動設定

process.env.NODE_ENVは、開発者が手動で指定するだけでなく、ツールやフレームワークが自動的に設定してくれる場合があります。特にReact（Create React App）やビルドツール（Webpack、Viteなど）では、この自動設定が大きな役割を果たします。

create-react-appを使って生成されたプロジェクトでは、package.jsonに次のようなスクリプトが定義されています。

"scripts": {
  "start": "react-scripts start",
  "build": "react-scripts build",
  "test": "react-scripts test",
  "eject": "react-scripts eject"
}

これらを実行すると、自動的にprocess.env.NODE_ENVの値が切り替わります。

Reactでの環境変数のルール

React（特に Create React App を使う場合）では、Node.jsのprocess.envをそのまま使えるわけではありません。セキュリティと運用上の理由から、特定のルールが設けられています。

Reactアプリでは、環境変数を参照するためにREACT_APP_というプレフィックスが必要です。このプレフィックスが付いていない環境変数は、アプリケーション内から参照できません。

例えば、環境変数を指定して実行する場合には、以下のようにします。

REACT_APP_MODE=staging npm start

アプリケーションで参照する際にもREACT_APP_を付けます。

const mode = process.env.REACT_APP_MODE;
console.log(mode);  // staging

MODEのようにREACT_APP_を付けなかった場合はundefinedになります。

MODE=staging npm start

実行結果を以下に示します。

const mode = process.env.MODE;
console.log(mode);  // undefined

このように、Reactでは必ずREACT_APP_を付けた環境変数だけが参照可能です。

package.jsonのスクリプトで環境変数を工夫する方法

ReactではREACT_APP_プレフィックスが必要ですが、毎回手で書くのは面倒です。そこでpackage.jsonのscriptsにまとめて定義しておくと便利です。

"scripts": {
  "start": "REACT_APP_MODE=$MODE react-scripts start",
  "build": "REACT_APP_MODE=$MODE react-scripts build"
}

こうしておけば、以下のように実行できます。

# ステージング環境
MODE=development npm start

アプリからは次のように参照できます。

console.log(process.env.REACT_APP_MODE); // development

環境が決まっている場合は、そのままscriptsに書いてしまってもOKです。

"scripts": {
  "start": "REACT_APP_MODE=development react-scripts start",
  "build": "REACT_APP_MODE=production react-scripts build",
  "build:dev": "REACT_APP_MODE=development react-scripts build"
}

アプリからは次のように参照できます。

console.log(process.env.REACT_APP_MODE); // development

本記事のまとめ

この記事では『環境変数とprocess.env』について説明しました。

process.envを理解して使いこなせば、アプリケーションを柔軟に環境ごとに切り替えることができます。

• 値はすべて文字列として扱われる
• プロセス起動時に読み込まれるため、後から変更しても自動更新されない
• NODE_ENVやPORTのような値で、挙動や接続先を切り替えるのに最適

といった特徴を押さえておけば、より安全でメンテナブルなコードが書けます。

お読み頂きありがとうございました。