笙亿网络策划

Cargo build 提示 linking with cc failed 错误如何排查？

约 7 分钟读完 4 阅
文章导读
Cargo build 提示 linking with cc failed 通常意味着系统缺少 C 编译器或相关开发库，最推荐的处理方向是根据操作系统安装对应的构建工具链（如 build-essential 或 Xcode Command Line Tools），并确认环境变量 CC 指向正确的编译器。
📋 目录
  1. Ⅰ 命令速用版
  2. Ⅱ 为什么会这样
  3. Ⅲ 分步处理
  4. Ⅳ 怎么验证是否生效
  5. Ⅴ 常见坑
  6. Ⅵ 常见问题
  7. Ⅶ 参考来源
A A

Cargo build 提示 linking with cc failed 通常意味着系统缺少 C 编译器或相关开发库，最推荐的处理方向是根据操作系统安装对应的构建工具链（如 build-essential 或 Xcode Command Line Tools），并确认环境变量 CC 指向正确的编译器。

先说结论：该错误绝大多数情况是系统未安装 C 语言编译器或链接器，导致 Cargo 在编译包含 native 依赖的 Rust 项目时失败，需优先安装系统级构建工具。

  • 先确认：在终端执行 which cc 或 cc `--version`，确认系统是否已安装可用的 C 编译器。
  • 先处理：根据操作系统安装对应的开发工具包，例如 Ubuntu/Debian 执行 sudo apt install build-essential，macOS 执行 xcode-select `--install`。
  • 再验证：安装完成后执行 cargo clean 清理缓存，再运行 cargo build 重新编译，观察错误是否消失。

命令速用版

以下命令可直接在对应系统的终端执行，用于快速安装 C 编译环境：

# Ubuntu/Debian
sudo apt update && sudo apt install build-essential pkg-config

# macOS (需先安装 Xcode Command Line Tools)
xcode-select `--install`

# CentOS/RHEL
sudo yum groupinstall "Development Tools"
sudo yum install gcc gcc-c++ make pkgconfig

# Windows (使用 rustup 安装 MSVC 工具链)
rustup toolchain install stable-x86_64-pc-windows-msvc
# 或安装 GNU 工具链（需额外配置）
rustup toolchain install stable-x86_64-pc-windows-gnu

为什么会这样

出现 linking with cc failed 的根本原因是 Cargo 在构建过程中调用了系统 C 编译器（cc）来链接 native 代码或依赖库，但系统环境中找不到可用的编译器或链接器。

Cargo build 提示 linking with cc failed 错误如何排查？

Rust 的许多 crate（如 openssl-sys、libz-sys）依赖 C 语言编写的底层库，Cargo 会通过 cc crate 自动调用系统的 C 工具链进行编译和链接。如果系统未安装 gcc、clang 或对应的开发头文件，链接步骤就会失败并报出该错误。

分步处理

步骤 1：确认 cc 是否可用
执行 which cc 查看编译器路径，再执行 cc `--version` 确认版本。如果返回“未找到命令”或类似提示，说明系统未安装 C 编译器。

步骤 2：安装系统构建工具
根据操作系统选择对应命令安装（见“命令速用版”）。注意：安装过程可能需要管理员权限，且会下载较大体积的软件包。

步骤 3：清理并重新构建
执行 cargo clean 清除之前失败的构建缓存，然后运行 cargo build -v 查看详细编译日志，确认链接步骤是否通过。

Cargo build 提示 linking with cc failed 错误如何排查？

步骤 4：检查特定依赖库
如果错误信息中提及具体库（如ssl、z），可能需要安装对应的开发包，例如 Ubuntu 上安装 libssl-dev、zlib1g-dev。可使用 pkg-config `--list-all` 检查库是否被系统识别。

怎么验证是否生效

执行 cargo build 后，观察终端输出是否以Finished dev [unoptimized + debuginfo] target(s) 结尾，且无 linking 相关错误。同时检查 target/debug/ 目录下是否生成了预期的二进制文件。运行该文件确认程序可正常启动，无动态库加载错误。

常见坑

  • 权限问题：安装系统包时忘记加 sudo，导致安装失败。务必确认当前用户有权限执行包管理命令。
  • 环境变量干扰：如果之前手动设置过 CC、CFLAGS 等环境变量，可能指向了不存在或版本不兼容的编译器。可执行 unset CC CFLAGS 临时清除后重试。
  • 多版本编译器冲突：系统同时安装了 gcc 和 clang，但 Cargo 默认调用的 cc 可能指向错误版本。可通过 export CC=clang 显式指定编译器。
  • 交叉编译场景：如果目标平台不是当前主机（如编译 ARM 版本），需安装对应的交叉编译工具链，并配置 .cargo/config.toml 指定链接器。

常见问题

必须安装 cc 才能编译 Rust 项目吗？

不一定。如果项目纯 Rust 编写且不依赖任何 native 库，则无需 C 编译器。但大多数实用 crate 会依赖 C 库，因此建议提前安装构建工具链。

Cargo build 提示 linking with cc failed 错误如何排查？

macOS 用户执行 xcode-select `--install` 后仍报错怎么办？

确认 Xcode Command Line Tools 是否安装成功，可执行 xcode-select -p 查看路径。如果路径不存在，尝试重新安装或手动从 Apple Developer 网站下载。

可以跳过 native 依赖的编译吗？

部分 crate 提供纯 Rust 实现的功能开关（features），可在 Cargo.toml 中禁用 native 依赖。但这样可能损失性能或功能，需根据项目需求权衡。

Windows 用户应该选择 MSVC 还是 GNU 工具链？

官方推荐使用 MSVC 工具链（stable-x86_64-pc-windows-msvc），其与 Windows SDK 集成更好。如果项目依赖的 C 库仅支持 MinGW，则需选择 GNU 工具链并额外安装对应编译器。

参考来源

  • Rust 官方书籍 - 安装 Rust：https://doc.rust-lang.org/book/ch01-01-installation.html
  • Cargo 文档 - 编译配置：https://doc.rust-lang.org/cargo/reference/config.html
  • cc crate 文档：https://docs.rs/cc
  • Rustup 文档 - 工具链管理：https://rust-lang.github.io/rustup/concepts/toolchains.html
  • Ubuntu 文档 - build-essential 包说明：https://packages.ubuntu.com/search?keywords=build-essential