← 中文资源

简体中文版本

Rust — linking with cc failed

从缺失本地库、错误的 target 工具链、feature 标志或重复符号诊断 Rust 链接错误,并修复构建环境。

阅读英文原文

链接器是最后一步

Rust 编译成功后调用系统链接器生成二进制。链接失败意味着编译器无法解析符号或找到库。读第一个 undefined reference 或调用中的 -l 标志;后面的输出通常是级联错误。

undefined reference to `SSL_new'
collect2: error: ld returned 1 exit status

本地依赖与 pkg-config

-sys crate 包装 C 库,需要库、头文件,往往还需要 pkg-config 元数据。在精简容器中安装 -dev 或 -devel 包,并验证 pkg-config --modversion。库在非标准前缀时设置 PKG_CONFIG_PATH。不要在没有匹配头文件的情况下直接 vendor 二进制。

Target 与工具链

musl target 生成静态二进制,但有些依赖需要 glibc 或 musl 不提供的系统库。CI 和本地要构建同一 target。更改工具链或 feature 后,如果可能缓存了旧对象或标志,运行 cargo clean。用 cargo build -vv 复现,并把命令保留在 issue 中。

验证产物

在目标环境运行二进制和测试;链接成功不代表运行时加载器能找到共享库。Linux 上用 ldd 或检查二进制依赖。在干净容器中构建,确保修复进入镜像,而不只在开发机上有效。