Node.jsのバージョン違いを直す｜ローカルとCIを同じ環境にそろえる

ローカルでは動くのにGitHub Actionsで失敗する。この差は、Node.jsを「最新版」へ上げるだけでは直らないことがあります。要求版を特定し、ローカル、設定ファイル、CIをそろえます。以下の24系は対象プロジェクトの対応版へ置き換えてください。

バージョン違いで起きる症状

Node.jsの版が違うと、同じソースとlockfileでも次のような差が出ます。

• Unsupported engineやEBADENGINEが表示される
• npm ci後のビルドやテストでエラーが出る
• ローカルは成功し、GitHub Actionsだけ失敗する
• 切り替えたはずなのに以前の版が表示される

ただし、npm、依存パッケージ、OS、環境変数、キャッシュが原因の場合もあります。最初に「実際の版」と「要求版」の差を証拠にします。CI全体の切り分けはGitHub Actionsで記事サイトを自動検品する方法も参考になります。

現在のNode.jsを確認する

プロジェクトのルートで実行します。

node --version
npm --version
Get-Command node

macOSやLinuxで実行場所を見る場合はcommand -v nodeです。古いNode.jsがPATH（コマンドの探索先）で先に見つかることがあるため、場所も見ます。GitHub Actionsでも2つの版を出し、結果を控えます。まだlockfileは削除しません。

プロジェクトの要求版を特定する

次の順で確認します。

1. package.jsonのengines.node
2. .nvmrc、.node-version、.tool-versions
3. GitHub Actionsのactions/setup-node
4. READMEと主要パッケージの対応範囲

{
  "engines": {
    "node": "24.x"
  }
}

npm公式資料ではenginesでNode.jsの版を指定できます。ただしengine-strictが無効なら警告扱いになる場面があり、実行版は自動的に切り替わりません。

指定が食い違う場合は、CIで実績がある版、デプロイ先、主要パッケージを照合します。Node.js公式は本番アプリにActive LTSまたはMaintenance LTSを推奨しています。2026年7月24日の公式表では24系と22系がLTS、26系がCurrentですが、導入時に再確認してください。

版を指定する場所の違い

設定場所	主な役割	自動で切り替わるか	向いている用途
package.jsonのengines.node	対応するNode.jsの範囲を伝える	npmの既定では切り替わらない	パッケージやアプリの対応条件
.nvmrc	nvm-sh/nvmが使う版を指定する	nvm useまたは連携設定が必要	macOS・Linuxのローカル開発
.node-version	対応ツールが読む版を指定する	使用ツールによる	複数の版管理ツールとの共有
actions/setup-node	CIで実際に使う版を用意する	ワークフロー実行時に切り替わる	GitHub Actions

1か所だけ直すのではなく、「対応条件」と「実際に使う版」の両方をそろえるのが要点です。指定ファイルを1つに集約したい場合は、GitHub Actionsのnode-version-fileから既存ファイルを参照できます。

バージョン管理ツールで切り替える

OSとチームの既存手順に合う管理ツールを1つ使います。macOS・Linuxのnvm-sh/nvmなら、次のように切り替えます。

nvm install 24
nvm use 24
node --version

プロジェクト直下の.nvmrcに24と書けば、引数なしのnvm installやnvm useがその指定を読みます。

WindowsのNVM for Windowsは別実装なので、版を明示します。

nvm install 24.18.0
nvm use 24.18.0
node --version

NVM for Windowsでは管理者権限が必要になる場合があります。macOS・Linux版nvmと同じ.nvmrcの自動切り替えは前提にしません。切り替わらなければ新しいターミナルでGet-Command nodeを確認し、1.1.11以降ならnvm debugでPATH競合を調べます。

package.jsonへ条件を残す

個人のPCだけ直しても、別の開発者や将来の自分には伝わりません。決めた条件をpackage.jsonへ残します。

{
  "engines": {
    "node": "24.x"
  }
}

CIも24系だけで検証するアプリなら24.x、複数メジャー版を支えるなら範囲を広げて各版でテストします。Node.jsの版と依存パッケージの固定は別なので、enginesを直しただけでlockfileを消しません。詳しくはnpm ciとnpm installの使い分けを確認してください。.nvmrcも同じメジャー版にします。

GitHub Actionsとそろえる

GitHub公式のactions/setup-nodeは、node-versionを省略するとランナーのPATHにあるNode.jsを使います。公式READMEはシステムへ依存せず、常に版を指定することを推奨しています。

steps:
  - uses: actions/checkout@v6
  - uses: actions/setup-node@v6
    with:
      node-version: '24'
      cache: 'npm'
  - run: node --version
  - run: npm ci
  - run: npm test

@v6は2026年7月24日に確認した公式READMEの例です。導入時には最新版と移行案内を再確認してください。

setup-nodeのnode-version-fileには、package.json、.nvmrc、.node-version、.tool-versionsを指定できます。たとえばnode-version-file: '.nvmrc'です。

Windowsでは.nvmrcをCIの基準ファイル、nvm use 24.18.0をローカル手順と分けます。CIだけ失敗するなら環境変数を読み込めないときの確認順へ進みます。

更新後に再検証する

修正後は、失敗したときと同じ順序を再現します。

node --version
npm --version
npm ci
npm test
npm run build

ローカルとCIのメジャー版が一致し、既存lockfileで導入でき、テストとビルドが成功したら完了です。失敗が残るなら、OS、パス、環境変数、権限、キャッシュへ調査範囲を移します。

よくある質問

EBADENGINEは無視してもよいですか

まずpackage.jsonのengines.nodeとnode --versionを比較してください。npmの既定では警告にとどまる場合がありますが、依存パッケージが現在の版で正常に動く保証にはなりません。対応範囲の版へそろえて再検証するのが安全です。

nvm useを実行してもNode.jsの版が変わらないのはなぜですか

別のNode.jsがPATHで先に見つかっている可能性があります。WindowsはGet-Command node、macOS・Linuxはcommand -v nodeで実体を確認します。NVM for Windows 1.1.11以降ではnvm debugもPATH競合の確認に使えます。

.nvmrcとpackage.jsonのenginesは両方必要ですか

役割が異なります。.nvmrcは主にローカルで使う版、enginesはプロジェクトが対応する範囲を伝えます。チームでnvm-sh/nvmを使うなら両方を同じメジャー版にそろえると、意図と実行環境のずれを減らせます。

Node.jsのメジャー版とパッチ版のどちらまで固定しますか

一般的なアプリでは、対応範囲は24.x、再現性を優先するローカルやCIは24.18.0のように固定する方法があります。ただし、セキュリティ修正の取り込み方針と更新頻度をチームで決め、固定したまま放置しないことが重要です。

Node.jsをそろえてもCIだけ失敗するときは何を見ますか

npm --version、OS、環境変数、権限、キャッシュの差を順に確認します。依存関係の導入差はnpm ciとnpm installの使い分け、秘密情報や設定値の差は環境変数を読み込めないときの確認順へ切り分けます。

一次情報

以下は2026年7月24日に確認しました。

• Node.js Releases：LTSと当日の版状態。
• npm package.json documentation：engines.nodeの書式と効力。
• actions/setup-node：版指定とnode-version-file。
• actions/setup-node Advanced usage：版指定ファイルの参照方法と優先順位。
• nvm-sh/nvm：.nvmrcの挙動。
• NVM for Windows：切り替えとPATH競合。
• NVM for Windows Common Issues：nvm debug、シンボリックリンク、PATH競合の切り分け。

現在値を測り、要求版を決め、ローカル、package.json、GitHub Actionsへ同じ条件を残します。最後はインストール、テスト、ビルドまで再実行します。