科技 · 实用指南
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。后面的编译器错误是另一类问题，因此从第一个因果错误开始，而不是只看最后的 npm 摘要。
同时保留日志里的命令路径。交互终端能执行 python3，只能证明该 Shell 能解析它，不能证明 npm 子进程使用相同 PATH、用户、环境或 node-gyp 副本。
证明真正运行的是哪个 Node、npm 与 node-gyp
在失败环境中记录 node -p "process.execPath"、node --version、npm --version，以及 gyp info 中的 node-gyp 版本与命令路径。检查 npm config get node_gyp 和相关包的安装脚本。只要包根目录存在 binding.gyp 且没有覆盖脚本，npm 就可能自动调用 node-gyp。
不要假设 npm install -g node-gyp 已改变失败安装使用的副本。官方维护文档说明部分 npm 版本带有内部 node-gyp，项目依赖或包管理器垫片还可能提供其他副本。以真实日志路径为准。
在同一子进程环境中测试 Python
在同一终端、容器层、服务账号或 CI 步骤中运行 command -v python3（Windows 用 where.exe python），再用返回的绝对路径执行 -c "import sys; print(sys.executable); print(sys.version)"。将其与 npm_config_python、PYTHON、NODE_GYP_FORCE_PYTHON 比较。交互式别名和 Shell 函数通常不会传给 npm 派生进程。
node-gyp 文档列出四个显式选择器：--python、npm_config_python、PYTHON 与 NODE_GYP_FORCE_PYTHON。强制变量若指向不兼容版本，会停止后续搜索。Windows 应用 py --list-paths 获取真实解释器路径，不要猜测商店别名。
把解释器版本与 node-gyp 版本配对
可执行文件存在仍可能被拒绝。当前 node-gyp 文档明确：Python 3.12 或更高版本需要 node-gyp 10 或更高版本。必须对照失败日志中的 node-gyp 版本，而不是另一个全局安装。
若日志先找到旧版或不受支持的 Python，删除过期选择器，或让失败进程指向兼容的绝对路径。只有理解升级会改变哪个 node-gyp 副本后，才升级包管理器或依赖链。不要因为旧社区答案就安装 Python 2。
区分解释器发现与下一阶段工具链故障
Python 选择成功后，以详细日志只重跑一次。若 find Python 消失，而首个错误转为 make、MSBuild、编译器、头文件、binding.gyp 或原生源码，说明解释器问题已经解决。此后应从新的首个错误继续，不要反复重装 Python。
Unix 上 node-gyp 需要受支持的 Python、make 和 C/C++ 编译器；Windows 需要受支持的 Python 与对应 Visual C++ 构建环境。Electron 等第三方运行时还可能需要自己的头文件。这些是独立分支。
只应用一个窄小、可回滚的选择器
优先在失败场景使用绝对解释器路径：直接调用 node-gyp 时传 --python，经 npm 安装时设置 npm_config_python。仅在需要更广泛环境契约时使用 PYTHON。NODE_GYP_FORCE_PYTHON 只应指向已验证兼容的解释器，因为它禁用回退搜索。
叠加新补丁前，先删除项目、用户、全局或 CI 中的过期值。npm 文档说明 npm_config_ 环境变量会成为配置参数，项目、用户与全局 npmrc 是不同作用域。记录修改作用域，不为单个作业写入全机配置。
在原场景验证并保留回滚证据
在完全相同的环境中重复原 npm 命令，确认详细日志显示预期 Python 绝对路径与兼容 node-gyp 版本，再验证原生模块能加载或测试通过。仅 node-gyp configure 成功并不能证明编译出的插件运行正常。
记录旧、新选择器值、node-gyp 路径、解释器路径、版本、npmrc 或 CI 作用域及删除命令。若这些变量不应控制其他项目，构建完成后清除临时 npm_config_python、PYTHON 或 NODE_GYP_FORCE_PYTHON。
