MacでNode-gypの再ビルドに失敗するエラーを解決する方法

node-gypは、開発者が複数のプラットフォーム向けにNode.jsのネイティブアドオンモジュールをコンパイルできる便利なツールです。現在では非常に人気が高く広く利用されているため、多くのNPMパッケージの依存関係として組み込まれています。

ほとんどのOSでは、node-gypは特に問題を起こしません。通常、インストールも他のNPMパッケージと同様にスムーズに完了します。しかし、すべてのユーザーに当てはまるわけではありません。一部の開発者からは、macOS上でnode-gypの再ビルドが失敗するという報告があり、開発体験を損なう事態が発生しています。このエラーはさまざまな落とし穴につながり、トラブルの原因にもなり得ます。

この問題は決して新しいものではありません。古いバージョンのmacOSを使用していた開発者も、以前から同様のエラーに遭遇していました。さらにmacOS Catalinaのリリース後には、新OSへアップグレードした後にnode-gypの再ビルドが失敗するという報告が多数寄せられました。このエラーにより、開発者が必要なnode-gypパッケージをインストールできなくなるケースも少なくありません。

このエラーに遭遇したことがある方なら、そのフラストレーションがどれほど大きなものか実感しているでしょう。この問題を解決しない限り、アプリやソフトウェアの開発を先に進めることはできません。幸い、解決策はいくつか存在します。プロジェクトが停滞してしまっている方は、以下の方法を順番に試してみてください。

プロのヒント：Macを定期的にスキャンして、パフォーマンス低下やシステム不具合の原因となるジャンクファイル、有害なアプリ、セキュリティ上の脅威を取り除きましょう。

Node-gypとは？

node-gypは、CまたはC++で記述されたネイティブなNode.jsモジュールである「Node.jsアドオン」をコンパイルするためのツールです。これらのモジュールは、node-gypのようなツールを使って各マシン上でコンパイルする必要があります。node-gypはWindows、macOS、Linuxのいずれでも動作します。

node-gypは一貫性のあるインターフェースを持つため、比較的扱いやすいのが特徴です。異なるプラットフォームでも同じコマンドでモジュールのビルドや再ビルドを行えます。また、複数のNode.jsターゲットバージョンにも対応しています。

Mojave以前のmacOSでnpm gypエラーが発生している場合は、まずnode-gypが動作するための要件を再確認しましょう。

macOSでnode-gypを動作させるために必要な要件は以下の通りです：

• Python v2.7、v3.5、v3.6、またはv3.7
• Xcode — macOS・iOS・iPadOS向けアプリの開発を可能にするユーティリティ

さらに、Xcodeのソフトウェア開発ツールおよびライブラリ群の一部である「Xcode Command Line Tools」の適切なバージョンもインストールする必要があります。

Xcode Command Line Toolsをインストールするには、以下の手順に従ってください：

1. MacでXcodeを起動します。
2. Xcodeメニューから環境設定（Preferences）を選択します。
3. 一般（General）パネル内のダウンロード（Downloads）をクリックします。
4. ダウンロードウィンドウが開いたら、コンポーネント（Components）タブを選択します。
5. Command Line Toolsの横にあるインストールボタンをクリックします。
6. Apple Developerアカウントでログインし、インストールを完了させます。

macOS Catalinaをお使いの場合は、お使いのCatalinaのバージョンに対応したCommand Line Tools for Xcodeをダウンロードしてください。たとえばmacOS 10.15.3の場合、ファイル名はCommand_Line_Tools_for_Xcode_11.3.1.dmgとなります。正しいコンポーネントをインストールすれば、node-gypでのビルドが成功するはずです。それでもMac上でnode-gypの再ビルドが失敗する場合は、これらのコンポーネントを見直して原因を特定しましょう。

Node-gypの再ビルドエラーを解決する方法

Nodeモジュールのインストール自体は簡単な作業です。所定のコマンドを実行すれば基本的には完了します。しかし「node-gyp rebuild fails on Mac」というエラーに遭遇した場合は、一度立ち止まって状況を整理する必要があります。

その前に、まず以下の基本的なトラブルシューティングを試してみてください：

1. PCを再起動して、システムに影響している可能性のある一時的なバグを取り除きます。
2. 不要なアプリをすべて終了し、システムリソースを解放します。
3. アンチウイルスやアンチマルウェアなどのセキュリティソフトを一時的に無効化します。
4. Mac修復アプリを使ってシステムをクリーンアップします。

それでもnode-gypの再ビルドエラーが解消されない場合は、以下の解決策を確認し、ご自身の環境に合ったものを試してください。

修正 #1：必要なコンポーネントを再確認する

Mojaveなど任意のmacOSバージョンでnpm gypエラーが発生した場合、最初に行うべきはnode-gypのインストール要件の再確認です。前述の通り、動作には次の3つのコンポーネントが必要です：

• Python
• Xcode
• Xcode Command Line Tools

モジュールのコンパイルに必要なCおよびC++言語環境のインストールも忘れないでください。これらのいずれかが欠けていたり正常に動作していなかったりすると、確実に再ビルドエラーが発生します。不足または破損しているコンポーネントを再インストールすることで、問題が解決するはずです。

修正 #2：Node-gyp関連のコンポーネントを更新する

コンポーネントをインストールするだけでは不十分な場合もあります。お使いのmacOSに適したバージョンを使用しているか必ず確認しましょう。Pythonはv2.7、v3.5、v3.6、v3.7の中から、自分の環境で動作するバージョンを選択できます。Xcodeは公式サイトから最新版をダウンロードしてください。念のため、node-gyp自体も最新バージョンにアップデートしておくことをおすすめします。

修正 #3：酸テスト（Acid Test）を実行する

お使いのマシンにXcode Command Line Toolsが正しくインストールされており、node-gypと連携できるかどうかは、以下の手順で酸テストを行うことで確認できます：

1. ターミナルで次のコマンドを実行します：
   /usr/sbin/pkgutil --packages | grep CL
2. 出力にcom.apple.pkg.CLTools_Executablesが表示されれば問題ありません。表示されない場合はテスト不合格となり、再インストールが必要です。
3. 続いて次のコマンドを実行します：
   /usr/sbin/pkgutil --pkg-info com.apple.pkg.CLTools_Executables
4. version: 11.0.0（以降）が表示されることを確認します。表示されない場合はこちらもテスト不合格のため、再インストールを行ってください。

修正 #4：別のPythonバージョンに切り替える

影響を受けた多くの開発者が、アクティブな環境で使用するPythonのバージョンを変更することで問題が解決したと報告しています。これは、macOSのバージョン、Node.jsのバージョン、そして使用しているPythonのバージョン間の互換性に関係しています。中には、v2.7のような旧バージョンのPythonの方が新しいバージョンよりも安定していると感じたユーザーもいます。複数のバージョンを試して、ご自身の環境に最適なものを見つけましょう。

まとめ

Macでnode-gypの再ビルドが失敗すると作業が滞り、原因の特定に多大な時間を費やすことになりかねません。このエラーに遭遇した場合は、本ガイドの手順を参考に、的確に対処していきましょう。