できない.dev

npm scripts で環境変数が設定できない(Windows で動かない)

"FOO=bar node app.js" の前置記法は POSIX シェル専用で、Windows 既定の cmd.exe では環境変数として解釈されない。
cross-env で OS 差を吸収するか、script-shell の変更や Node.js の --env-file で対処する。

公開: 更新:

症状できない
npm run build
> env-demo@1.0.0 build
> NODE_ENV=production node build.js

'NODE_ENV' は、内部コマンドまたは外部コマンド、
操作可能なプログラムまたはバッチ ファイルとして認識されていません。

2026-10-15 に local host (Windows 11 Home, Docker 29.8.0)(npm 10.9.2 / Node.js 22.14.0) で実際に打って取った出力。検証環境の詳細

要約

"build": "NODE_ENV=production node build.js" のような npm scripts が Windows で「'NODE_ENV' は、内部コマンドまたは外部コマンド…として認識されていません」と失敗するのは、FOO=bar command という環境変数の前置が POSIX シェルの構文だからだ。
npm scripts は POSIX 環境では sh、Windows では cmd.exe で実行される(npm config の script-shell(新しいタブで開く))。
cmd.exe はこの記法を解釈できないため、環境変数が設定できないどころかコマンド自体が失敗する。

実行例

Windows 11 の npm で NODE_ENV=production node build.js と書いた script を動かすと、'NODE_ENV' は、内部コマンドまたは外部コマンド…として認識されていません で止まった。
set NODE_ENV=production && node build.js に変えると動くものの値が [production ] と末尾に空白つきで入り、cross-env と node --env-file=.env では [production] が読めている。

$ npm run build
> env-demo@1.0.0 build
> NODE_ENV=production node build.js
 
'NODE_ENV' は、内部コマンドまたは外部コマンド、
操作可能なプログラムまたはバッチ ファイルとして認識されていません。
$ npm run build
> env-demo@1.0.0 build
> set NODE_ENV=production && node build.js
 
NODE_ENV=[production ]
$ npm install --save-dev cross-env
$ npm run build
> env-demo@1.0.0 build
> cross-env NODE_ENV=production node build.js
 
NODE_ENV=[production]
$ npm run build
> env-demo@1.0.0 build
> node --env-file=.env build.js
 
NODE_ENV=[production]

— 2026-10-15 時点の出力

検証環境Node.js 22.14.0 / npm 10.9.2 / Git 2.48.1.windows.1 / 2026-10-15 検証(ほか 1 件)
検証日
実行環境
local host (Windows 11 Home, Docker 29.8.0)
バージョン
  • Node.js 22.14.0
  • npm 10.9.2
  • Git 2.48.1.windows.1
  • Docker 29.8.0

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

1. cross-env で OS 差を吸収する

npm install --save-dev cross-env
{
  "scripts": {
    "build": "cross-env NODE_ENV=production node build.js"
  }
}

cross-env が変数設定を OS ごとの正しい方法に変換するため、同じ script が Windows / macOS / Linux で動く。

2. script-shell を POSIX シェルに変更する

npm config set script-shell "C:\\Program Files\\Git\\bin\\bash.exe"

Git Bash を npm scripts の実行シェルにすると、前置記法や $FOO がそのまま動く。
ただし、チーム全員がこの設定をしておく必要がある。

3. --env-file で .env を読み込む

node --env-file=.env app.js

Node.js 20.6 以降は --env-file フラグで .env ファイルを process.env に読み込める。
シェル非依存なので npm scripts に書いても OS を問わず動作する。

よくある原因

  1. 前置記法は sh 専用の構文である。
    FOO=bar node app.js は、sh が「この 1 コマンドの間だけ FOO を設定する」と解釈する。
    cmd.exe では FOO=bar を実行ファイル名として探しに行く。
  2. set で設定した値に空白が混入している。
    cmd.exe 流に set FOO=bar && node app.js と書くと、bar と && の間の半角スペースが値の末尾に入り、比較が一致しなくなる。
  3. npm scripts は .env を自動では読み込まない。
    dotenv や --env-file などの明示的な仕組みが必要になる。
  4. 変数の参照記法が違う。
    スクリプト内の $FOO は cmd.exe では展開されず、%FOO% は sh では展開されない。