エラーメッセージ
npm installを実行した際に、ターミナルが突然赤いエラーテキストで埋め尽くされる経験は誰にでもあるでしょう。node-sass、bcrypt、sharpなどのパッケージをインストールすると、システムはネイティブのC++コードをコンパイルしようとします。Windowsでは、このプロセスが以下のエラーで失敗することがよくあります。
gyp ERR! build error
gyp ERR! stack Error: `msbuild` failed with exit code: 1
gyp ERR! stack at ChildProcess.onExit (C:\Program Files\nodejs\node_modules\npm\node_modules\node-gyp\lib\build.js:194:23)
gyp ERR! System Windows_NT 10.0.19045
gyp ERR! node -v v18.16.0
gyp ERR! node-gyp -v v9.3.1
gyp ERR! not ok
原因：なぜWindowsでネイティブアドオンが失敗するのか
JavaScriptは多機能ですが、常に処理速度において最適なツールであるとは限りません。パフォーマンスが重視されるパッケージでは、CやC++で書かれた「ネイティブアドオン」が使用されます。WindowsにはデフォルトでC++コンパイラが含まれていないため、これらのアドオンをビルドするツールであるnode-gypは、ソースコードを動作可能なバイナリに変換する方法が分からずエラーになります。
MSBuildからのexit code: 1は、一般的な「失敗」の合図です。通常、セットアップにおける以下の3つのいずれかの欠落を指しています：
- ツールの不足： Visual Studio C++ Build Toolsがインストールされていない。
- ワークロードの間違い： Visual Studioはあるが、「C++によるデスクトップ開発」パッケージをスキップしている。
- パスの混乱：
node-gypがPythonや正しいバージョンのMicrosoft Build Engineを見つけられない。
ステップバイステップの解決方法
1. Visual Studio Build Toolsのインストール
これは、90%のユーザーに有効な根本的な解決策です。15GBもあるVisual Studio IDEを丸ごと入れる必要はありません。スタンドアロンのBuild Toolsだけで十分です。
- Visual Studio Build Tools インストーラーをダウンロードします。
- インストーラーを起動します。ワークロード画面が表示されたら、C++によるデスクトップ開発にチェックを入れます。
- 右側のインストールの詳細パネルを確認します。MSVC v143（VS 2022用）とWindows 10または11 SDKが選択されていることを確認してください。
- 約2GB〜4GBのダウンロードが必要です。インストールをクリックし、完了したらPCを再起動します。
2. npmに正しいバージョンを指示する
システムに複数のバージョンのVisual Studioがインストールされていると、ビルドプロセスが混乱することがあります。管理者権限のPowerShellで以下を実行し、npmに使用するバージョンを明示的に伝えます：
npm config set msvs_version 2022
Visual Studio 2019を使用している古い環境の場合は、代わりに2019を使用してください。
3. Pythonのインストールを確認する
node-gypはビルドロジックの管理にPythonスクリプトを使用します。Microsoft Store経由でPythonをインストールした場合、自動的にPATHが通っているはずです。しかし、エラーが解消されない場合は、npmの設定で手動でパスを指定してください：
npm config set python C:\Users\YourName\AppData\Local\Programs\Python\Python311\python.exe
C:\Users\... フォルダを確認し、バージョン番号（例：Python311）が実際にディスク上にあるものと一致しているか確認してください。
4. クリーンな再試行（Nuclear Refresh）
ツールを修正した後でも、古いビルドの残骸が原因でnode-gypが失敗し続けることがあります。プロジェクトのローカルロックと一時ファイルを削除して、一旦リセットしましょう：
# node_modulesとロックファイルを削除
rmdir /s /q node_modules
del package-lock.json
# すべて再インストール
npm install
確認：ビルドのテスト
うまくいきましたか？npm installがすべて終わるのを待たずに、特定のパッケージを個別にビルドして修正を確認できます：
cd node_modules/bcrypt
node-gyp rebuild
最後にgyp info okと表示されれば、環境はネイティブコードを扱う準備が整っています。
今後のための対策
今後このような問題を避けるために、以下の戦略を検討してください：
- JSのみの代替パッケージへの切り替え：
bcryptの代わりにbcryptjsを使用します。純粋なJavaScriptパッケージは20〜30%遅くなる可能性がありますが、コンパイラを必要とせず、あらゆるOSに即座にインストールできます。 - WSL2への移行： Windows Subsystem for Linux (WSL2)内での開発は、多くの場合よりスムーズです。
gccやmakeなどのLinuxツールは、重いWindows Build Toolsよりも管理がはるかに簡単です。 - プリコンパイル済みバイナリの使用： 可能であれば、「prebuilds」（OSに合わせたバイナリファイル）を提供しているパッケージを選択してください。これにより、コンパイル工程を完全にスキップできます。