Node.js バージョンが合わず EBADENGINE で警告される
package.json の engines.node とインストール環境の Node バージョンが食い違うと npm は EBADENGINE を出す。
nvm / fnm / volta で要求バージョンに切り替えるか、engines を実態に合わせて更新するのが基本対応。
公開:
要約
npm warn EBADENGINE Unsupported engine は package.json の engines.node とインストール環境の Node バージョンが合わない警告。engines を実態に合わせて緩めるか、nvm / fnm / volta で要求バージョンに切り替えるかの二択。
CI とローカルの Node バージョンを揃えると再発しない。
よくある原因
- engines が厳しすぎる: 自分のプロジェクトの
engines.nodeが>=20などで、現在の Node 18 と合わない - 依存側の engines: 深い依存が新しい Node を要求し、
npm installでトランジティブに EBADENGINE が出る .nvmrc未更新: チームでバージョンを上げたのに自分のローカルだけ古い Node のまま- CI 不一致:
actions/setup-nodeのnode-versionがローカルと違い、片方だけ警告が出る
解決策
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"
}
}要求が過度に厳しい場合は緩める。engineStrict を使う環境では警告ではなくエラーで止まるため、定義は実装の最低動作バージョンと一致させる。
仕様は npm 公式の package.json ドキュメント に記載。
3. volta でプロジェクト pin
volta pin node@20
volta pin npm@10package.json の volta フィールドにバージョンが書き込まれ、リポジトリに入った全員が自動的に同じバージョンを使う。
Node を切り替え忘れる事故を仕組みで防げる。
4. CI のバージョンを揃える
# GitHub Actions
- uses: actions/setup-node@v4
with:
node-version-file: .nvmrcnode-version-file を .nvmrc に向ければローカルと CI が常に一致する。
別バージョン同士で webpack や native module のキャッシュがズレる事故も減る。
実行例
実際に上記の手順を node:20 環境で動かすと、engines.node を >=99.0.0 と設定した状態では npm error code EBADENGINE が発生して終了コード 1 で止まり、値を実環境（v20.20.2）が満たせる範囲に修正した再実行では終了コード 0 で完了することを確認できる。
== versions ==
PRETTY_NAME="Debian GNU/Linux 12 (bookworm)"
v20.20.2
Python 3.11.2
git version 2.39.5
This is not the tsc command you are looking for
To get access to the TypeScript compiler, tsc, from the command line either:
- Use npm install typescript to first add TypeScript to your project before using npx
- Use yarn to avoid accidentally running code from un-installed packages
v10.5.0
== run ==
使用中の Node: v20.20.2
--- npm install （EBADENGINE で失敗を想定）---
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-06-25T02_35_28_420Z-debug-0.log
npm install の終了コード: 1
--- 解消: engines.node を実環境で満たせる範囲に更新 ---
--- 再実行（成功を想定）---
up to date, audited 1 package in 267ms
found 0 vulnerabilities
npm install の終了コード: 0（0 なら解消）— 2026-06-25 時点の出力