Antigravity で Node.js バージョンの不一致エラーが出た時の対処法

「npm install したら突然エラーになった」「昨日まで動いていたのに今日だけ失敗する」——そういうとき、原因の大半は Node.js のバージョン不一致だったりします。

Antigravity のエージェントが自動でパッケージをインストールしたり、新しいプロジェクトをセットアップする際に、実行環境の Node バージョンが想定と異なることで失敗するケースは珍しくありません。しかも「エラーメッセージがわかりにくくて何が起きているか把握しにくい」という問題もあります。

ここではよくある Node.js バージョンエラーのパターンとその修正方法を、実際のエラーメッセージ例とともに整理しました。

よくあるエラーメッセージと原因

まずエラーの種類を確認しましょう。Node.js バージョン不一致には、大きく3パターンがあります。

パターン1: npm の engines フィールドによる警告・エラー

npm warn EBADENGINE Unsupported engine {
  package: 'some-package@3.0.0',
  required: { node: '>=20.0.0' },
  current: { node: 'v18.17.0', npm: '9.6.7' }
}

このエラーは「このパッケージは Node 20 以上を要求しているが、実行環境は Node 18 だ」という意味です。npm warn は警告のみのことも多いですが、npm error EBADENGINE になっている場合はインストール自体が中断されます。

パターン2: ネイティブモジュールのビルド失敗

gyp ERR! configure error
gyp ERR! stack Error: Node.js v18.17.0 is not supported

node-gyp でネイティブコードをコンパイルするパッケージで起きます。canvas、sqlite3、sharp などがよく該当します。

パターン3: ES Modules や構文の互換性エラー

SyntaxError: Cannot use import statement in a module

Node.js 12 以前では ESM（ECMAScript Modules）を標準で使えないため、現代的なパッケージをインストールすると失敗します。

まず現在の Node バージョンを確認する

エラー修正の前に、Antigravity のターミナルで実行環境を把握します。

# 現在の Node.js バージョン
node -v
 
# npm のバージョン
npm -v
 
# nvm がインストールされているか確認
nvm --version 2>/dev/null || echo "nvm not installed"
 
# インストール済みの Node バージョン一覧
nvm list 2>/dev/null

Antigravity のターミナルはシェルの設定（.zshrc や .bashrc）を読み込むため、システムの node とは別のバージョンが使われていることがあります。もしバージョンが意図したものと違う場合は、次のセクションの設定を確認してください。

.nvmrc でバージョンを固定する

プロジェクト単位で Node バージョンを指定するには、.nvmrc ファイルが最もシンプルな方法です。

# プロジェクトルートに .nvmrc を作成（例: Node 20.x を指定）
echo "20" > .nvmrc
 
# または正確なバージョンを指定
echo "20.12.0" > .nvmrc

.nvmrc があると、ターミナルで nvm use を実行するだけで適切なバージョンに切り替わります。

# .nvmrc のバージョンに切り替え
nvm use
 
# 出力例
Found '/path/to/project/.nvmrc' with version <20>
Now using node v20.12.0 (npm v10.5.0)

Antigravity のエージェントがターミナルコマンドを実行する際も、この .nvmrc を認識してくれます。プロジェクトに .nvmrc を置いておくと、「このプロジェクトは Node 20 を使う」という情報がエージェントにも伝わりやすくなります。

package.json の engines フィールドを設定する

package.json に engines フィールドを追加すると、要求する Node バージョンを明示できます。これはチーム開発や CI/CD でバージョン違いを防ぐのに有効です。

{
  "name": "my-project",
  "engines": {
    "node": ">=20.0.0",
    "npm": ">=10.0.0"
  }
}

さらに .npmrc に以下を追加すると、バージョン不一致時に警告ではなくエラーとして扱われます。

engine-strict=true

これにより、Antigravity のエージェントが npm install を実行した際に即座に問題が表示されるため、原因特定が早くなります。

nvm がインストールされていない場合

macOS や Linux で nvm を使っていない場合は、公式のインストールスクリプトで導入できます。

# nvm のインストール（最新版はhttps://github.com/nvm-sh/nvmを確認）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
 
# シェルを再起動（または設定ファイルを読み込む）
source ~/.zshrc   # zsh の場合
source ~/.bashrc  # bash の場合
 
# Node 20 をインストールして使う
nvm install 20
nvm use 20
nvm alias default 20   # デフォルトに設定

nvm alias default 20 を忘れると、ターミナルを開き直したときに古いバージョンに戻ってしまいます。Antigravity の統合ターミナルも新しいシェルとして起動するため、デフォルト設定が重要です。

Dev Container を使っているプロジェクトでの対処

Dev Container を使ったプロジェクトでは、.devcontainer/devcontainer.json の image や features で Node バージョンを固定できます。

{
  "name": "My App",
  "image": "mcr.microsoft.com/devcontainers/javascript-node:20",
  "features": {
    "ghcr.io/devcontainers/features/node:1": {
      "version": "20"
    }
  }
}

この方法だと「Dev Container を使うすべての環境で同じ Node バージョン」が保証されます。チーム開発やCI/CDで最も確実な方法です。

pnpm や Bun を使っている場合

プロジェクトが pnpm のモノレポや Bun ランタイムを採用している場合、Node バージョン管理の挙動が異なります。

pnpm の場合:

# pnpm はpackage.json の engines フィールドを標準でチェックします
# より厳格なチェックにするには .npmrc に以下を追加
node-version=20.0.0

Bun の場合: Bun 自体は Node.js とは別のランタイムですが、node_modules の互換性のために内部でNodeのネイティブAPIを呼び出すパッケージがあります。Bun を使っていてもシステムの Node が古いとビルドエラーになることがあります。Bun を使うプロジェクトでは bun --version に加えて node -v も確認しておきましょう。

対処後の確認

修正が完了したら、以下で正常に動作するか確認します。

# バージョンの確認
node -v   # 期待するバージョンか？
 
# クリーンインストールで確認（キャッシュを除外）
rm -rf node_modules package-lock.json
npm install
 
# または
pnpm install

Antigravity のエージェントに「このプロジェクトをクリーンインストールして動作確認して」と頼む際、.nvmrc や engines フィールドが設定済みであれば、エージェントも正しいバージョンの前提でコマンドを実行してくれます。

プロジェクトに .nvmrc を追加する——これが今日できる最初の一歩です。Antigravity との協業がより安定するはずです。