Claude Codeが「Node.jsバージョンが古い」と言い続ける——node -vは最新なのに直らない原因を実例で切り分ける
npm install時のEBADENGINE警告は実は無害なのに、VSCode拡張機能だけ「Node.js 18以上が必要」と拒否してくる謎をGitHub Issueで検証。nvm/volta環境でPATHがGUIアプリに渡らない根本原因と、Mac/Windows/Linux別の対処法。
エンジニアのゆとです。
npm install -g @anthropic-ai/claude-codeを実行すると、大量の黄色い警告が流れて「うわ、失敗した」と思う人と、VSCode拡張機能を開いた瞬間にError: Claude Code requires Node.js version 18 or higher to be installedと出て、node -vで確認したら普通に新しいバージョンが入っているのに直らない、という人がいる。
実はこの2つ、原因がまったく別物だ。片方は無視していい警告で、片方はPATHの解決タイミングに起因する実在のバグに近い挙動。混同したまま「Node.jsを再インストールする」みたいな遠回りの対処に走ると時間を溶かす。公式ドキュメントとGitHub Issueの実際のやり取りを見比べながら、どのパターンかを切り分けていく。
結論 — まず自分がどっちの症状か表で確認する
| 症状 | 原因 | 対処の方向性 |
|---|---|---|
npm install -g実行時に大量の警告(npm warn EBADENGINE)が出るが、claudeコマンド自体は動く | 無害。v2.1.198以降、npmパッケージはNode.js 22以上を要求するようになったが、古いNodeでは警告止まりで実害はない | 気持ち悪ければNodeを22以上に上げる。急ぎでなければ放置でいい |
ターミナルのclaudeは正常なのに、VSCode拡張機能だけ「Node.js version 18 or higher」で止まる | GUIで起動したVSCodeが、nvm/voltaがPATHに追加したNodeを見つけられていない | シェル設定ファイルの読み込み範囲を見直す（後述） |
node -vは最新なのにエラーが消えない | ターミナルとGUIアプリで参照する設定ファイルが違う（~/.zshrcと~/.profileなど） | GUIアプリ起動時の環境変数の伝搬経路を直す |
| Windowsのネイティブ環境で同じエラーが出続ける | インストール方式（npm/ネイティブインストーラー）の不整合 | ローカルインストールへの切り替えを試す |
ケース1: npm installのEBADENGINE警告は、実は無視していい
公式ドキュメントの「Install with npm」の項目に、地味だけど重要な一文がある。
As of v2.1.198, the npm package requires Node.js 22 or later. On an older Node.js version, npm prints an
EBADENGINEwarning during install rather than failing; the install completes andclaudestill runs, since the package downloads a native binary that doesn’t use your Node.js at runtime.
要約すると、@anthropic-ai/claude-codeのnpmパッケージは、実行時にNode.jsのランタイムを使っていない。インストール時にプラットフォームごとのネイティブバイナリ（@anthropic-ai/claude-code-darwin-arm64など）をoptionalDependencyとして落としてきて、postinstallスクリプトでそれをclaudeコマンドとして配置しているだけだ。つまりnpmは「パッケージの動作要件」としてNode.js 22以上を宣言しているけど、それはあくまでnpmのエンジンチェックの話であって、claudeコマンド自体の実行にNode.jsは関与しない。
古いNode.js環境でnpm install -g @anthropic-ai/claude-codeを実行すると、こういう警告が出る。
npm warn EBADENGINE Unsupported engine {
npm warn EBADENGINE package: '@anthropic-ai/claude-code@2.1.xxx',
npm warn EBADENGINE required: { node: '>=22.0.0' },
npm warn EBADENGINE current: { node: 'v18.20.4', npm: '10.7.0' }
npm warn EBADENGINE }見た目は派手だけど、これは「インストールが失敗した」わけではなく「動作要件を満たしていないよ」という警告に過ぎない。インストール自体は最後まで完了し、claude --versionを実行すればバージョン番号が返ってくるはずだ。
claude --version
# 2.1.211 (Claude Code) のように表示されればOK気持ち悪さが残るなら、nvmでNode.js 22以上に上げてから入れ直せば警告自体が消える。
nvm install 22
nvm use 22
npm install -g @anthropic-ai/claude-codeただし、この節の話は「CLIとしてのclaudeコマンド」限定の話だ。次のケースは似たエラーメッセージなのに原因が全然違う。
ケース2: VSCode拡張機能だけ「Node.js version 18 or higher」で止まる
こっちが本題。GitHubのIssueに、まさにこの症状の報告が立っている。
報告者の環境ではNode.js v24.9.0が入っていて、ターミナルからclaudeを叩けば普通に動く。それでもVSCode拡張機能を開くとError: Claude Code requires Node.js version 18 or higher to be installedが表示され続ける。コメント欄で複数人が「自分も同じ」と報告していて、原因の推測としてmarkgohoが「nvmが関係してるかも」とコメントし、その後LIdroが実際の根本原因と解決策を突き止めている。
根本原因 — GUIアプリはターミナルと同じ環境変数を見ていない
nvmやvoltaでNode.jsをインストールすると、インストーラーは~/.bashrcや~/.zshrcにPATH追加のコードを書き込む。これらはインタラクティブシェル（ターミナルを開いたときに毎回読み込まれる設定ファイル）だ。
一方、Dockやスタートメニュー、Spotlightからアプリを直接起動した場合、そのアプリは「ログインシェル」や「システムの環境変数」は引き継ぐけど、~/.bashrcや~/.zshrcは読み込まない。VSCodeをGUIから起動した場合がまさにこれで、nvmが追加したはずのNodeのパスがVSCode拡張機能からは見えていない。だから拡張機能は「Node.jsが見つからない、あるいはバージョンが古いシステム標準のNode.jsしか見えない」と判断してエラーを出す。
LIdroの投稿によると、Linux環境での確認済みの原因はこう説明されている。
The issue occurs because VS Code launched from the GUI doesn’t inherit the PATH from nvm (which is set in ~/.bashrc).
ターミナルからcode .でVSCodeを開いた場合は、その時点でシェルのPATHをすでに継承しているので、同じ症状が起きにくい。これが「ターミナルのclaudeは動くのに拡張機能だけ死ぬ」現象の正体だ。
Macでの直し方
自分がふだん使っているのはMacなので、ここは実際に近い環境で確認しやすい方法から並べる。
対処1: VSCodeは必ずターミナルから開く
一番手っ取り早いのはこれ。DockやSpotlightから直接VSCodeを起動する習慣をやめて、プロジェクトディレクトリでターミナルを開いてからcode .で起動する。
cd ~/projects/my-app
code .こうするとVSCodeはターミナルのシェル環境（~/.zshrcで設定したnvmのPATHを含む）をそのまま引き継いだ状態で立ち上がる。運用でカバーする分、一番失敗しにくい。
対処2: バージョンマネージャーをやめてHomebrewでシステム全体にNode.jsを入れる
nvmは「シェルの設定ファイルにPATHを追記する」方式なので、GUI起動との相性が根本的に良くない。プロジェクトごとにNodeのバージョンを切り替える必要がないなら、Homebrewで一本化してしまうのも有効だ。
brew install node
which node
# /opt/homebrew/bin/node のようにHomebrew配下を指していればOKHomebrewでインストールした場合、/opt/homebrew/binは/etc/paths.d/経由でmacOSのシステム全体のPATHに登録される。ログインシェル・GUIアプリのどちらからでも同じNodeが見えるようになるので、シェル設定ファイルの読み込みタイミングに依存しなくなる。
対処3: GUIアプリにもPATHを伝搬させる(launchctl setenv)
nvmを使い続けたい場合は、macOSのlaunchd経由でGUIアプリ全体にPATHを伝える方法もある。~/.zprofile（ログインシェルで読まれる設定ファイル）に以下を追記して、ログインし直す。
# ~/.zprofile に追記
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
launchctl setenv PATH "$PATH"launchctl setenvはログインセッション全体に環境変数を伝える仕組みで、これ以降にDockやSpotlightから起動したGUIアプリにもPATHが反映される。反映には一度ログアウト・ログインし直すか、再起動が必要になる。
Windowsでの直し方
Windows環境での報告では、dapperdandevが投稿した対処法が有効だったという返信がついている。
claude migrate-installerこれはnpmでグローバルインストールしたClaude Codeを、ローカル（ユーザー単位）のネイティブインストールに切り替えるコマンドだと報告されている。実行後、プロンプトに従い、開いているシェルとVSCodeを一度すべて閉じて開き直す。npm経由のインストールはグローバルなnode_modules配下にインストールされる関係で、システムのNode.js環境やPATHの状態に引きずられやすい。ネイティブインストールに切り替えると、その依存関係を切り離せる。
念のため補足すると、これは公式ドキュメントの「Advanced setup」ページには明記されていない、Issueコメント上で報告された対処法だ。効果には個人差があるので、まずは自分の環境で試す前提で見てほしい。
Linuxでの直し方
Linux環境については、LIdroが投稿した手順がIssue内で「これで直った」と複数人から反応を得ている、実質のベストアンサーだ。
~/.profileにnvmの設定を追記する。
# ~/.profile に追記
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"systemdの環境変数設定ファイルを用意し、使っているNode.jsのバージョンに合わせてPATHを明示する。
mkdir -p ~/.config/environment.d
echo 'PATH=$HOME/.nvm/versions/node/v22.16.0/bin:$PATH' > ~/.config/environment.d/node.conf
# v22.16.0 の部分は自分の node -v の結果に置き換える設定後、一度ログアウトしてログインし直す（あるいは端末を再起動する）と、GUI経由で起動したVSCodeでもNode.jsが認識されるようになる。
それでも直らないときのチェックリスト
上記を試しても直らない場合、次のあたりを疑う。
- 複数のNode.jsが競合していないか。
which -a nodeで全パスを洗い出し、Homebrew版・nvm版・OS標準パッケージ版などが同時に入っていないか確認する - プロジェクト直下に
.nvmrcがあり、そこで固定されたバージョンとグローバルのバージョンがズレていないか - VSCode拡張機能自体が古くないか。Issue内では「拡張機能とVSCode本体を最新にアップデートしたら直った」という報告もある。まずは
code --list-extensions --show-versionsで拡張機能のバージョンを確認し、最新化を試す claude doctorを実行して、インストール状態と設定ファイルの診断結果を確認する
claude doctorclaude doctorはセッションを開始せずに、インストールの健全性・設定ファイルのバリデーションエラー・推奨される修正を読み取り専用で表示してくれる。原因の切り分けに詰まったら、まずこれを実行するのが早い。
再発防止 — バージョンマネージャーの運用を見直す
根本原因は「バージョンマネージャーがシェルの設定ファイルにPATHを書き込む方式」であること自体にある。nvmを使い続けるなら、ターミナル経由でGUIアプリを起動する習慣を徹底するのが一番シンプルだ。
頻繁にこの手の問題を踏むようなら、シェルの設定ファイルに依存せずシム（実行ファイルを差し替える方式）でバージョンを切り替えるツールへの乗り換えも検討する価値がある。運用を変えるコストと、毎回PATHのトラブルシューティングをするコストを天秤にかけて判断すればいい。
FAQ
npm warn EBADENGINEが出たままでもclaudeを使い続けて大丈夫？
大丈夫。npmパッケージのエンジン要件チェックが警告を出しているだけで、claudeコマンドの実体はNode.jsランタイムに依存しないネイティブバイナリだ。ただし将来のバージョンでこの許容範囲が変わる可能性はゼロではないので、余裕があるタイミングでNode.js 22以上に上げておくと安心ではある。
node -vで確認したバージョンと、Claude Codeが認識しているバージョンが違うのはなぜ？
ターミナルでnode -vを実行したときのシェルと、VSCode拡張機能がNode.jsを探しにいく実行コンテキストが別物だから。ターミナルは~/.zshrcなどを読み込んだ状態、GUIアプリはそれを読み込んでいない状態、という違いが典型的な原因になる。
CLI版とVSCode拡張機能、結局どちらを使うべき？
このエラーに繰り返し悩まされるなら、当面はターミナルからCLI(claude)を直接使う運用に寄せてしまうのも現実的な回避策だ。拡張機能側の環境検出の実装が改善されるまで待つ、という判断も間違いではない。CLIと拡張機能の使い分け自体を整理した記事もあるので参考にしてほしい。
まとめ
「Node.jsバージョンが古い」というエラーメッセージは同じでも、npm installのEBADENGINE警告と、VSCode拡張機能が出す実行時エラーは別物だ。前者は実害のない警告、後者はGUIアプリがシェルのPATH設定を引き継げていないことが原因になっているケースが大半だった。
まずclaude --versionとclaude doctorで自分の状態を診断し、CLIとVSCode拡張機能のどちらで症状が出ているかを切り分ける。それさえできれば、あとはOSごとの対処法をそのまま当てはめるだけで解決に近づくはずだ。
