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

要約

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

よくある原因

1. engines が厳しすぎる: 自分のプロジェクトの engines.node が >=20 などで、現在の Node 18 と合わない
2. 依存側の engines: 深い依存が新しい Node を要求し、npm install でトランジティブに EBADENGINE が出る
3. .nvmrc 未更新: チームでバージョンを上げたのに自分のローカルだけ古い Node のまま
4. 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@10

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

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

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

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

実行例

実際に上記の手順を 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
npm install の終了コード: 1

$ npm install
up to date, audited 1 package in 131ms
 
found 0 vulnerabilities
npm install の終了コード: 0（0 なら解消）

— 2026-08-02 時点の出力