テクノロジー · 実用ガイド
node-gyp が Python を見つけない？再インストール前に実行パスを証明する
実際の npm 子プロセス、node-gyp のコピー、Python セレクター、互換性条件を追跡してから環境を変更します。
「端末で Python が動く」と「node-gyp がその Python を使える」は別の事実です。実際の npm 子プロセスと選択経路を先に証明します。
発見、バージョン受理、ネイティブツールチェーンの順に最初の失敗段階を特定し、変更を小さく可逆に保ちます。
最初の失敗とインストール環境を固定する
最初の gyp ERR! find Python から最終コマンドまで、作業ディレクトリと各バージョンを保存します。npm install、npm ci、パッケージスクリプト、コンテナ、CI のどれかも記録します。
ログのコマンドパスも保存します。対話シェルで python3 が動いても、npm 子プロセスが同じ PATH、ユーザー、環境、node-gyp を使う証明にはなりません。
実際に動いた Node・npm・node-gyp を特定する
失敗環境で node -p "process.execPath"、Node/npm の版、gyp info の node-gyp 版とパスを記録します。npm config get node_gyp とインストールスクリプトも確認します。
グローバルな node-gyp の導入だけで npm が使うコピーが変わったとは限りません。内部同梱、プロジェクト依存、シムの可能性があるため、実ログを基準にします。
同じ子プロセス環境で Python を試す
同じ端末、コンテナ層、サービスアカウント、CI ステップで Python の絶対パスと sys.executable、sys.version を確認し、npm_config_python、PYTHON、NODE_GYP_FORCE_PYTHON と比較します。
公式の選択肢は --python、npm_config_python、PYTHON、NODE_GYP_FORCE_PYTHON です。強制指定が不適合なら探索は続きません。Windows は py --list-paths を使います。
Python と node-gyp の版を合わせる
Python が存在しても版が不適合なら拒否されます。公式文書では Python 3.12 以上は node-gyp 10 以上が必要です。失敗ログの版と比較します。
古い Python が先に選ばれる場合は古い指定を除くか、互換な絶対パスを指定します。実際のコピーが変わると確認してから更新し、古い回答だけを根拠に Python 2 を入れません。
検出失敗と次のビルド失敗を分ける
Python が選ばれたら詳細ログで一度だけ再実行します。最初のエラーが make、MSBuild、コンパイラ、ヘッダー、binding.gyp、ソースへ移れば検出問題は解決済みです。
Unix では make と C/C++ コンパイラ、Windows では Visual C++ 環境が別途必要です。Electron などは専用ヘッダーが必要な場合があります。
狭く可逆なセレクターを一つ設定する
直接 node-gyp を呼ぶなら --python、npm 経由ならその工程で npm_config_python を使います。広い契約が必要な場合だけ PYTHON を使い、強制指定は互換性確認後に限ります。
プロジェクト、ユーザー、グローバル、CI の古い値を先に除去します。npm_config_ と各 npmrc の作用域を記録し、一つのジョブのために全体を変えません。
元の環境で再検証しロールバックを残す
同じ環境で元の npm コマンドを再実行し、意図した Python パスと互換版を確認してからネイティブモジュールのロードやテストを行います。configure 成功だけでは不十分です。
旧値と新値、各パス、版、作用域、解除コマンドを記録します。他のプロジェクトへ影響させない場合は一時変数を解除します。
