できない.dev

Node.js バージョンが合わず EBADENGINE で警告される

package.json の engines.node とインストール環境の Node バージョンが食い違うと npm は EBADENGINE を出す。
nvm / fnm / volta で要求バージョンに切り替えるか、engines を実態に合わせて更新するのが基本対応。

公開: 更新:

症状できない · exit 1
npm install
…
npm error code EBADENGINE
npm error engine Unsupported engine
npm error engine Not compatible with your version of node/npm: demo@1.0.0
npm error notsup Not compatible with your version of node/npm: demo@1.0.0
解決後できた · exit 0
npm install
up to date, audited 1 package in 131ms

found 0 vulnerabilities

2026-08-02 に node:20 で実際に打って取った出力。検証環境の詳細

要約

npm warn EBADENGINE Unsupported engine は package.json の engines.node とインストール環境の Node バージョンが合わないことを知らせる警告である。
直し方は、engines を実態に合わせて緩めるか、nvm / fnm / volta で要求バージョンに切り替えるかの二択になる。
CI とローカルの Node バージョンを揃えると再発しない。

実行例

node:20 環境で上記の手順を動かすと、engines.node を >=99.0.0 と設定した状態では npm error code EBADENGINE が発生し、終了コード 1 で止まった。
値を実環境(v20.20.2)が満たせる範囲に修正して再実行すると、終了コード 0 で完了した。

$ node -v
v20.20.2
$ npm install
npm error code EBADENGINE
npm error engine Unsupported engine
npm error engine Not compatible with your version of node/npm: demo@1.0.0
npm error notsup Not compatible with your version of node/npm: demo@1.0.0
npm error notsup Required: {"node":">=99.0.0"}
npm error notsup Actual:   {"npm":"10.8.2","node":"v20.20.2"}
npm error A complete log of this run can be found in: /root/.npm/_logs/2026-08-02T08_44_37_263Z-debug-0.log
$ echo $?
1
$ npm install
up to date, audited 1 package in 131ms
 
found 0 vulnerabilities
$ echo $?
0

— 2026-08-02 時点の出力

検証環境2026-08-02 検証
検証日
実行環境
node:20

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

解決策

1. nvm / fnm でバージョンを揃える

# nvm
nvm install 20
nvm use 20
 
# fnm
fnm install 20
fnm use 20

プロジェクトに .nvmrc があれば nvm use だけで自動選択される。
バージョンを上げたら .nvmrc も同じ commit で更新し、レビューで気付けるようにする。

2. engines を現実に合わせる

{
  "engines": {
    "node": ">=20.11.0"
  }
}

要求が過度に厳しい場合は緩める。
.npmrc に engine-strict=true を書いた環境では警告ではなくエラーで止まるため、定義は実装の最低動作バージョンと一致させる。
仕様は npm 公式の package.json ドキュメント(新しいタブで開く) に書かれている。

3. volta でプロジェクト pin

volta pin node@20
volta pin npm@10

package.json の volta フィールドにバージョンが書き込まれ、リポジトリに入った全員が自動的に同じバージョンを使う。
Node を切り替え忘れる事故を仕組みで防げる。

ただし Volta は 2025 年 11 月から保守されておらず、公式は mise(新しいタブで開く) への移行を勧めている。
これから固定の仕組みを入れるなら、1 の nvm / fnm か mise を使う。

4. CI のバージョンを揃える

# GitHub Actions
- uses: actions/setup-node@v4
  with:
    node-version-file: .nvmrc

node-version-file を .nvmrc に向ければローカルと CI が常に一致する。
別バージョン同士で webpack や native module のキャッシュがズレる事故も減る。

よくある原因

  1. engines が厳しすぎる。
    自分のプロジェクトの engines.node が >=20 などで、現在の Node 18 と合わない。
  2. 依存側の engines に引っかかっている。
    深い依存が新しい Node を要求し、npm install でトランジティブに EBADENGINE が出る。
  3. .nvmrc の更新に追従していない。
    チームでバージョンを上げたのに、自分のローカルだけ古い Node のままになっている。
  4. CI とローカルでバージョンが違う。
    actions/setup-node の node-version がローカルと違い、片方だけ警告が出る。