跨平台编译 ​

核心概念 ​

跨平台编译(cross-compilation)是在一个平台上编译出另一个平台可运行的二进制文件。例如在 Windows 上编译 Linux 的可执行程序,或者在 x86 电脑上编译 ARM 嵌入式设备的固件。Rust 对跨平台编译有良好的支持,通过 rustup target add 安装目标平台的标准库,配合 cargo build --target 即可完成。

跨平台编译的难点在于链接器和系统库。纯 Rust 代码通常可以直接交叉编译,但如果依赖 C 库(通过 FFI),则需要目标平台的交叉编译工具链。cross 工具通过 Docker 容器自动解决这些依赖问题。

bash
# 基本的跨平台编译流程

# 1. 查看当前主机目标
# rustc --version --verbose

# 2. 安装目标平台标准库
# rustup target add x86_64-unknown-linux-musl
# rustup target add aarch64-unknown-linux-gnu
# rustup target add x86_64-pc-windows-gnu

# 3. 交叉编译
# cargo build --target x86_64-unknown-linux-musl --release

# 4. 查看已安装的目标
# rustup target list --installed

常见交叉编译场景 ​

主机平台目标平台目标三元组用途
WindowsLinux x64x86_64-unknown-linux-gnu服务器部署
WindowsLinux muslx86_64-unknown-linux-musl静态链接部署
macOSLinux x64x86_64-unknown-linux-gnuDocker/服务器
x86_64ARM64 Linuxaarch64-unknown-linux-gnu树莓派/ARM 服务器
任意WebAssemblywasm32-unknown-unknown浏览器/WASI
任意ARM 嵌入式thumbv7em-none-eabihf微控制器

配置链接器 ​

toml
# .cargo/config.toml
# 为不同目标配置链接器

[target.x86_64-unknown-linux-gnu]
linker = "x86_64-linux-gnu-gcc"

[target.aarch64-unknown-linux-gnu]
linker = "aarch64-linux-gnu-gcc"

[target.x86_64-unknown-linux-musl]
linker = "x86_64-linux-musl-gcc"

# 也可以使用 lld 作为链接器(更快)
[target.x86_64-unknown-linux-gnu]
linker = "rust-lld"
rustflags = ["-C", "linker-flavor=ld.lld"]

使用 cross 工具 ​

bash
# cross 通过 Docker 自动提供交叉编译工具链
# 不需要手动安装链接器和系统库

# 安装 cross
# cargo install cross

# 使用 cross 代替 cargo(用法完全相同)
# cross build --target x86_64-unknown-linux-gnu --release
# cross build --target aarch64-unknown-linux-gnu --release
# cross test --target x86_64-unknown-linux-gnu

# cross 自动下载并使用对应的 Docker 镜像
# 镜像中包含了目标平台的编译器、链接器和系统库

静态链接(musl) ​

bash
# musl 目标生成完全静态链接的二进制文件
# 不依赖系统的 glibc,可以在任何 Linux 上运行

# 安装 musl 目标
# rustup target add x86_64-unknown-linux-musl

# 编译静态二进制
# cargo build --target x86_64-unknown-linux-musl --release

# 验证是否静态链接(Linux 上)
# file target/x86_64-unknown-linux-musl/release/my-app
# ldd target/x86_64-unknown-linux-musl/release/my-app
# 输出 "statically linked" 表示完全静态链接

基本示例 ​

rust
// 跨平台兼容的代码

fn get_config_dir() -> String {
    #[cfg(target_os = "windows")]
    {
        std::env::var("APPDATA").unwrap_or_else(|_| ".".to_string())
    }

    #[cfg(target_os = "linux")]
    {
        std::env::var("XDG_CONFIG_HOME").unwrap_or_else(|_| {
            let home = std::env::var("HOME").unwrap_or_else(|_| "/tmp".to_string());
            format!("{}/.config", home)
        })
    }

    #[cfg(target_os = "macos")]
    {
        let home = std::env::var("HOME").unwrap_or_else(|_| "/tmp".to_string());
        format!("{}/Library/Application Support", home)
    }

    #[cfg(not(any(target_os = "windows", target_os = "linux", target_os = "macos")))]
    {
        ".".to_string()
    }
}

fn get_line_ending() -> &'static str {
    if cfg!(windows) {
        "\r\n"
    } else {
        "\n"
    }
}

fn main() {
    println!("配置目录: {}", get_config_dir());
    println!("操作系统: {}", std::env::consts::OS);
    println!("架构: {}", std::env::consts::ARCH);
    println!("可执行文件后缀: '{}'", std::env::consts::EXE_SUFFIX);
    println!("换行符长度: {}", get_line_ending().len());
}

CI/CD 多平台构建 ​

toml
# Cargo.toml — 跨平台项目配置
[package]
name = "my-cli"
version = "0.1.0"
edition = "2024"

[profile.release]
opt-level = 3
lto = "thin"
strip = "symbols"
yaml
# GitHub Actions 多平台构建示例(仅供参考)
# .github/workflows/release.yml
#
# jobs:
#   build:
#     strategy:
#       matrix:
#         include:
#           - target: x86_64-pc-windows-msvc
#             os: windows-latest
#           - target: x86_64-unknown-linux-musl
#             os: ubuntu-latest
#           - target: aarch64-unknown-linux-musl
#             os: ubuntu-latest
#           - target: x86_64-apple-darwin
#             os: macos-latest
#     runs-on: ${{ matrix.os }}
#     steps:
#       - uses: actions/checkout@v4
#       - run: rustup target add ${{ matrix.target }}
#       - run: cargo build --release --target ${{ matrix.target }}

常见问题 ​

问题一:交叉编译时找不到链接器怎么办?

安装目标平台的交叉编译工具链,或使用 cross 工具。Windows 上可以用 WSL 来编译 Linux 目标。也可以使用 zig 作为万能链接器:配置 linker = "zig cc" 。

问题二:有 C 依赖的项目怎么交叉编译?

使用 cross 工具(基于 Docker),它自动提供目标平台的 C 编译器和系统库。也可以手动安装交叉编译工具链并配置环境变量。

问题三:musl 和 gnu 目标有什么区别?

gnu 目标动态链接 glibc,需要目标系统有兼容版本的 glibc。musl 目标静态链接 musl libc,生成的二进制不依赖系统库。musl 二进制更便携但可能略慢。

问题四:怎么为多个平台同时构建?

使用 CI/CD(如 GitHub Actions)的矩阵构建策略,在不同的 runner 上并行构建。或者用 cross 在本地依次构建多个目标。

适用场景 ​

  • 服务器部署:在开发机上编译 Linux 服务器二进制
  • 嵌入式开发:编译 ARM 微控制器固件
  • Docker 镜像:用 musl 目标生成最小静态二进制
  • 多平台发布:为 Windows/Linux/macOS 构建发布包

注意事项 ​

  • 纯 Rust 代码交叉编译通常无障碍
  • 有 C 依赖时需要目标平台的交叉编译工具链
  • cross 工具通过 Docker 简化交叉编译
  • musl 目标生成静态链接二进制,便携性好
  • .cargo/config.toml 配置目标链接器
  • #[cfg(target_os)] 处理平台差异代码

总结 ​

跨平台编译通过 rustup target add 安装目标标准库、cargo build --target 编译。纯 Rust 代码通常可直接交叉编译,有 C 依赖时需要目标平台的工具链或使用 cross 工具。musl 目标生成完全静态链接的二进制,适合 Docker 和便携部署。.cargo/config.toml 配置目标链接器。代码中用 #[cfg(target_os)] 和 cfg!() 处理平台差异。CI/CD 中用矩阵构建策略为多个平台同时构建发布包。