Zig 赋能 Rust 交叉编译：手动脚本与 cargo-zigbuild 实战指南

Zig

Zig 是一门新兴的系统编程语言，其内置的强大交叉编译能力（包括完整的 libc/sysroot 支持）可以赋能 Rust 轻松解决跨平台编译构建问题，避免了手动安装和管理特定的交叉编译工具链（如 C/C++ 链接器）。

安装 Zig

brew install zig

zig version
# 0.15.2

Mac/aarch64 平台构建 Linux/amd64 平台的包

1. 手动脚本封装

创建一个拦截 Cargo 执行的 shell 脚本 zigcc-x86_64-linux-gnu，主要是拦截 Cargo 的 CC/linker 调用，注入 Zig 的 --target 参数，并处理 C/C++ 模式切换。

在 Rust 根目录下创建 zigcc-x86_64-linux-gnu 文件

#!/bin/bash

new_args=()
for arg in "$@"; do
  if [[ "$arg" == --target=x86_64-unknown-linux-gnu ]]; then
    new_args+=("--target=x86_64-linux-gnu")
  else
    new_args+=("$arg")
  fi
done

# Detect if C++: check for .cc/.cpp/.cxx input files
is_cpp=false
for arg in "${new_args[@]}"; do
  if [[ "$arg" == *.cc || "$arg" == *.cpp || "$arg" == *.cxx ]]; then
    is_cpp=true
    break
  fi
done

# Exec with correct mode and mapped args
if [ "$is_cpp" = true ]; then
  exec zig c++ "${new_args[@]}"
else
  exec zig cc "${new_args[@]}"
fi

赋予执行权限

chmod +x zigcc-x86_64-linux-gnu

替换 Rust 的 x86_64-unknown-linux-gnu 为 x86_64-linux-gnu: Zig 需要精确的 3 部分 triple 来选择正确的工具链和 sysroot，不需要 unknown
zig c++: 处理 .cc/.cpp/.cxx 后缀的文件
zig cc: Zig 会用内置 LLD 链接器，处理 .rlib 和 .o 文件

编译构建

cargo clean --target x86_64-unknown-linux-gnu
cargo build --target x86_64-unknown-linux-gnu --release

2. 使用 cargo-zigbuild

cargo-zigbuild 是 Rust 社区的专用工具，它封装了 Zig 的 CC/linker，支持自动 sysroot 管理和多平台。比手动脚本简单，适合 CI/CD 或快速迭代。

安装 cargo-zigbuild 并配置 rustup 支持的目标平台

cargo install --locked cargo-zigbuild
rustup target add x86_64-unknown-linux-gnu

注释 .cargo/config.toml

编译构建

cargo clean --target x86_64-unknown-linux-gnu
cargo zigbuild --target x86_64-unknown-linux-gnu --release

自动注入 Zig 的 CC/AR/linker 到 Cargo 的 build 流程
自动映射 triple、提供 sysroot，并处理 C/C++ 依赖

3. Mac 平台可能的错误

文件描述符配额超出

    error: unable to search for static library '/Volumes/Samsung/Workspace/project/rust/zig-rust-cross/target/x86_64-unknown-linux-gnu/release/deps/libzerotrie-ededb43a4c4ed898.rlib': ProcessFdQuotaExceeded

ProcessFdQuotaExceeded: 表示编译进程尝试打开太多的文件，比如 libzerotrie-ededb43a4c4ed898.rlib，超出了 macOS 为单个进程设置的文件描述符（File Descriptor, FD）限制

查看当前值

ulimit -n
# 256

调高

ulimit -n 8192

4. 上述两种方法都会在以下路径中成功构建出二进制程序包

/target/x86_64-unknown-linux-gnu/release/zig-rust-cross

结语

利用 Zig 出色的交叉编译能力，可以轻松打包分发 Rust 程序，这为不依赖 Docker 的场景（例如嵌入式系统或硬件苛刻的环境）提供了一种轻量级替代方案。手动脚本方法适合学习研究或深度定制，而 cargo-zigbuild 则更适合日常开发与生产执行。