Cargo 报构建脚本失败并给出令人困惑的退出状态

症状

构建失败并报 failed to run custom build command for a crate，后跟构建脚本错误或掩盖真实消息的退出状态。构建脚本会编译并探测原生依赖，因此失败通常是缺少系统库、缺少 pkg-config 之类的工具，或脚本所需的环境变量缺失。在缺少开发头文件的 CI 镜像上尤为常见。

诊断

用 -vv 运行查看脚本输出；安装缺失的系统依赖或工具；按脚本期望设置环境变量并复现探测命令。

cargo build -vv 2>&1 | grep -A20 "build command"

根因

构建脚本无法完成，因为它所依赖的系统库、工具或环境变量在构建环境中缺失或不可发现。

修复

安装缺失的系统库或工具；设置脚本期望的环境变量；确保构建环境与开发机具有相同的依赖。

验证

重新构建确认脚本完成，再运行 crate 确认其链接到所探测到的原生库。成功链接并运行即证明环境已满足脚本。

常见陷阱

在 CI 里静默跳过依赖检测会让构建看似通过而产物缺少原生支持；应显式安装依赖。