npm 编译原生模块报 No module named distutils：旧 node-gyp 遇到 Python 3.12
npm 编译原生模块遇到 distutils 缺失时，检查实际 node-gyp 与 Python 路径。Python 3.12 需兼容构建工具，更新被调用的依赖链，保留临时环境与原生 ABI 验收边界。
npm 安装原生模块时停在 node-gyp rebuild，日志包含 ModuleNotFoundError: No module named 'distutils'，并显示 Python 3.12 与 node-gyp 8.x 或 9.x。先核对这次构建真正调用的 node-gyp 和 Python：Python 3.12 已从标准库移除 distutils，旧构建工具仍可能导入它。
当前 node-gyp 文档明确，Python 3.12 及以上需要 node-gyp 10 或更高。这是构建工具与解释器的兼容边界，不是 npm 下载缓存或数据库配置问题。不同原生包可能带着自己的工具依赖，终端上的全局 node-gyp 版本不一定参与本次安装。
从失败日志确认实际依赖链
查看完整日志中 gyp info using node-gyp、find Python、spawn 和失败脚本路径。下面只是要关注的日志格式示例：
gyp info using node-gyp@8.4.1
gyp info find Python using Python version 3.12.8
.../node_modules/node-gyp/gyp/pylib/gyp/input.py
from distutils.version import StrictVersion
日志若明确从旧 gyp 的 input.py 导入 distutils，符合这条处理路径。若导入来自另一 Python 项目、解释器不是 3.12，或真正失败的是 C++ 编译错误，应继续按实际堆栈检查，不只凭末尾 gyp ERR! 归类。
项目内可查看依赖树，例如下面的诊断命令。它只说明安装树中有哪些依赖，仍要与实际调用路径对照；非零结果可能表示依赖树存在问题：
npm ls node-gyp --all
检查安装脚本调用的是原生包自带版本、包管理器附带版本，还是项目自己的构建入口。全局安装新版工具，不会自动改写另一包在 node_modules 中锁定的旧副本。
更新实际被调用的构建工具
优先寻找原生模块、上层依赖或包管理器的受支持版本，使实际构建链使用兼容 Python 3.12 的 node-gyp。更新哪一层由调用路径决定，不能只在根 package.json 里加一个新版依赖就声称所有嵌套副本已替换。
修改前保存 package.json、锁文件、构建镜像与 Node、Python 版本。在隔离环境按项目的依赖更新流程调整，并检查新的日志确实使用预期版本。依赖覆盖功能可能改动上游未验证过的组合，应先核对包管理器语义和原生包兼容性，不把强制覆盖当作默认方案。
node-gyp 10 是这项 Python 兼容的最低边界，不是所有项目应永久固定的最新版本。它不能保证原生模块同时兼容当前 Node ABI、目标平台和编译工具链；若构建进入下一阶段后出现新的 C++ 错误，应继续处理那一阶段。
临时保留旧工具时，只调整受控构建环境
暂时无法更新上层依赖时，可评估使用仍受项目和供应方支持、且与旧构建链兼容的 Python 环境。Python 3.11 保留 distutils，但具体分发环境是否完整仍应检查；不能把任意旧解释器当作长期部署目标。
多解释器环境可以按实际 node-gyp 版本的配置入口选择 Python。直接调用支持 --python；PYTHON 与 NODE_GYP_FORCE_PYTHON 也有各自选择规则。后者会覆盖其他搜索路径，不兼容时不会继续找另一份解释器。设置应限定在这次构建或 CI 作业，并保存原值以便恢复，不替换系统 Python 来修一个项目。
部分旧环境可通过相同解释器中的 setuptools 获得兼容 distutils，但这仍是兼容措施，需核对上层项目要求。不要仅运行一个不知归属的 pip；也不要把安装 packaging 当成能保证旧代码中的 from distutils 导入成功。新版构建链应沿其自身依赖设计解决。
重建成功以后，验证原生模块还能加载
用原来的项目安装入口重新验证，确认日志中的实际工具和解释器已按设计改变，distutils 导入不再阻断 configure。安装脚本会执行构建动作并可能下载头文件，应在获准的隔离环境完成，不在运行中的应用目录直接覆盖依赖。
然后检查目标平台生成的原生模块能由实际 Node 运行时加载，应用需要的功能正常。仅 configure 通过，还不能证明编译、链接和运行时 ABI 都兼容；不要从另一架构或 Node 版本的机器复制 .node 文件来跳过构建。
需要回退时恢复锁文件、构建环境及原应用版本，并按原流程重新生成依赖。回退一份全局工具不会恢复已经变动的项目安装树；保留已知可用构建产物和对应版本，避免继续混用两套结果。