科技 · 實用指南
node-gyp 找不到 Python？重裝前先證明直譯器路徑
先追蹤實際 npm 子程序、node-gyp 副本、Python 選擇器與版本相容門檻，再改別名、重裝工具鏈或寫入全域設定。
「終端機能執行 Python」與「node-gyp 能使用該 Python」是不同主張。先證明實際 npm 子程序、node-gyp 副本、選擇器與相容門檻。
本指南沿著直譯器發現、版本接受及獨立原生工具鏈找出第一個失敗階段，讓每個變更都可驗證、可回復。
凍結第一個錯誤與安裝情境
保存從第一條 gyp ERR! find Python 到最終命令的完整輸出，以及工作目錄與 Node、npm、node-gyp 版本。註明錯誤來自 npm install、npm ci、安裝腳本、容器或 CI。
同時保存日誌中的命令路徑。終端機可執行 python3 只代表該 Shell 能解析它，不代表 npm 子程序使用相同 PATH、使用者或 node-gyp。
證明真正執行的 Node、npm 與 node-gyp
在失敗環境記錄 node -p "process.execPath"、版本與 gyp info 中的命令路徑。檢查 npm config get node_gyp 及套件安裝腳本；binding.gyp 可讓 npm 自動呼叫 node-gyp。
不要假設全域安裝已改變 npm 實際使用的副本。部分 npm 版本含內部副本，專案依賴與墊片也可能提供其他版本；以失敗日誌為準。
在相同子程序環境測試 Python
在同一終端、容器層、服務帳號或 CI 步驟查詢 python3 的絕對路徑並輸出 sys.executable 與 sys.version，再與 npm_config_python、PYTHON、NODE_GYP_FORCE_PYTHON 比對。
node-gyp 支援 --python、npm_config_python、PYTHON 與 NODE_GYP_FORCE_PYTHON。強制變數若不相容會停止搜尋；Windows 用 py --list-paths 取得真實路徑。
配對直譯器與 node-gyp 版本
Python 存在仍可能被拒絕。官方文件指出 Python 3.12 以上需要 node-gyp 10 以上；請比對失敗日誌中的版本。
若先找到舊版 Python，移除過期選擇器或指定相容絕對路徑。確認升級會改變實際副本後才升級，不要依舊答案安裝 Python 2。
區分發現錯誤與下一個工具鏈錯誤
Python 被接受後只重跑一次詳細日誌。若首錯改為 make、MSBuild、編譯器、標頭或原生碼，表示發現問題已解決。
Unix 還需要 make 與 C/C++ 編譯器；Windows 需要 Visual C++ 環境；第三方執行環境可能需要自己的標頭。這些是獨立分支。
套用一個窄小且可回復的選擇器
直接呼叫 node-gyp 時用 --python；透過 npm 時在該步驟設定 npm_config_python。只有需要廣泛環境契約時才用 PYTHON，強制變數必須先驗證相容。
新增修補前移除專案、使用者、全域或 CI 的過期值。npm_config_ 會成為設定參數，而不同 npmrc 有不同作用域。
在原情境驗證並保存回復證據
在相同環境重跑原 npm 命令，確認詳細日誌顯示預期 Python 路徑與相容 node-gyp，再測試原生模組載入。configure 成功不等於執行成功。
記錄新舊值、路徑、版本、作用域與移除命令。若不應影響其他專案，建置後清除臨時選擇器。
