症状
本篇指南处理“node-gyp 构建失败 — 原生扩展无法编译”。请从症状出发，按顺序执行诊断，在推进前确认每个假设；随后通过修复与验证步骤闭环。
可观察到的症状包括：
- npm install 报 “gyp ERR! build error” 并返回非零退出码
- 数据库或加密类传递依赖报告 node-gyp 错误
- 开发机可用，但在精简 CI 容器中失败
诊断
先在隔离环境中复现故障，再按顺序执行以下检查，逐步缩小范围。
步骤 1
npm install --verbose 2>&1 | grep -A 20 "gyp ERR!"第一段 gyp ERR! 会点出真正原因：缺少编译器、头文件或 Python 出错。
步骤 2
cc --version && make --version && python3 --version任一缺失都会导致构建错误；在 Debian slim 镜像上安装 build-essential 与 python3。
步骤 3
npm config set nodedir /path/to/node && node -p "process.versions.modules"让头文件匹配 ABI 版本（process.versions.modules）可解决离线网络中的下载失败。
常见诱因（按出现频率排序）：
- 构建环境中缺少 C++ 编译器或 make
- 当前 Node ABI 版本的头文件未下载，或被代理拦截
- 缺少 Python，或检测到的 python 指向已移除 distutils 的 Python 3.12
根因
原生扩展通过 node-gyp 针对 Node 头文件编译 C++。当编译器、Python 构建垫片或匹配 ABI 的头文件缺失时，node-gyp 无法完成 configure 与 make 步骤，构建随即失败。
修复
安装构建工具链（build-essential、python3、make、g++），配置 Node 头文件下载，并尽量通过 npm config set 或 prebuild-install 覆盖来使用预编译二进制。
注意：预编译二进制可免去编译，但必须匹配平台与 ABI；不匹配的预编译会在运行时报错，而非构建时。
# Debian/Ubuntu build image
apt-get update && apt-get install -y build-essential python3 make g++
# Force header download and retry
npm install --build-from-source --verbose
# Or prefer prebuilt addons
npm config set prefer-offline true验证
在干净环境重跑 npm install，确认扩展编译成功或预编译下载成功。随后在 Node 中 require 该模块并调用一个方法，证明二进制可加载。
修复后补充一条回归测试，复现原始症状，防止问题再次出现。
这类故障通常是环境问题而非纯逻辑错误，因此在缺陷记录中应写明完整命令、环境变量与工作目录。请用最小的脚本复现，待最小用例清楚后再扩大范围。为这类故障准备一份简短的排查清单，能显著减少下次排障时间。