条件依赖 target ​

核心概念 ​

条件依赖(target-specific dependencies)允许根据目标平台来选择性地引入依赖。不同操作系统和架构可能需要不同的库,比如 Windows 上用 winapi,Linux 上用 nix。Cargo 通过 [target.'cfg(...)'.dependencies] 语法来声明平台相关的依赖,只有在匹配的目标平台上才会编译和链接这些依赖。

toml
# 根据操作系统选择依赖
[target.'cfg(windows)'.dependencies]
winapi = { version = "0.3", features = ["winuser", "processthreadsapi"] }
windows-sys = "0.52"

[target.'cfg(unix)'.dependencies]
nix = { version = "0.28", features = ["signal", "process"] }
libc = "0.2"

[target.'cfg(target_os = "macos")'.dependencies]
core-foundation = "0.9"

# 根据架构选择依赖
[target.'cfg(target_arch = "x86_64")'.dependencies]
simd-json = "0.13"

cfg 表达式 ​

toml
# === 操作系统 ===
[target.'cfg(windows)'.dependencies]        # Windows
[target.'cfg(unix)'.dependencies]           # Unix 系统(Linux, macOS, BSD 等)
[target.'cfg(target_os = "linux")'.dependencies]   # 仅 Linux
[target.'cfg(target_os = "macos")'.dependencies]   # 仅 macOS
[target.'cfg(target_os = "android")'.dependencies] # Android

# === 架构 ===
[target.'cfg(target_arch = "x86_64")'.dependencies]  # x86-64
[target.'cfg(target_arch = "aarch64")'.dependencies]  # ARM64
[target.'cfg(target_arch = "wasm32")'.dependencies]   # WebAssembly

# === 逻辑组合 ===
[target.'cfg(all(unix, not(target_os = "macos")))'.dependencies]
# Unix 但不是 macOS(主要是 Linux 和 BSD)

[target.'cfg(any(target_os = "linux", target_os = "macos"))'.dependencies]
# Linux 或 macOS

[target.'cfg(not(windows))'.dependencies]
# 非 Windows

# === 其他条件 ===
[target.'cfg(target_env = "musl")'.dependencies]   # musl libc
[target.'cfg(target_pointer_width = "64")'.dependencies]  # 64 位
[target.'cfg(target_endian = "little")'.dependencies]     # 小端序
cfg 表达式说明
windowsWindows 系统
unixUnix 系统
target_os = "linux"Linux
target_os = "macos"macOS
target_arch = "x86_64"x86-64 架构
target_arch = "aarch64"ARM64 架构
target_env = "gnu"GNU 工具链
target_env = "msvc"MSVC 工具链
all(a, b)a 且 b
any(a, b)a 或 b
not(a)非 a

条件 dev-dependencies 和 build-dependencies ​

toml
# 平台特定的开发依赖
[target.'cfg(windows)'.dev-dependencies]
windows-test-utils = "0.1"

[target.'cfg(unix)'.dev-dependencies]
nix = { version = "0.28", features = ["signal"] }

# 平台特定的构建依赖
[target.'cfg(windows)'.build-dependencies]
winres = "0.1"      # Windows 资源文件编译

[target.'cfg(unix)'.build-dependencies]
pkg-config = "0.3"  # Unix 系统库查找

基本示例 ​

toml
[package]
name = "cross-platform"
version = "0.1.0"
edition = "2024"

[dependencies]
# 所有平台都需要的依赖
log = "0.4"

[target.'cfg(windows)'.dependencies]
winapi = { version = "0.3", features = ["winuser"] }

[target.'cfg(unix)'.dependencies]
libc = "0.2"
rust
// 在代码中配合条件依赖使用条件编译

#[cfg(windows)]
fn get_username() -> String {
    // Windows 上获取用户名
    std::env::var("USERNAME").unwrap_or_else(|_| "unknown".to_string())
}

#[cfg(unix)]
fn get_username() -> String {
    // Unix 上获取用户名
    std::env::var("USER").unwrap_or_else(|_| "unknown".to_string())
}

#[cfg(windows)]
fn platform_info() -> &'static str {
    "Windows"
}

#[cfg(target_os = "linux")]
fn platform_info() -> &'static str {
    "Linux"
}

#[cfg(target_os = "macos")]
fn platform_info() -> &'static str {
    "macOS"
}

fn main() {
    println!("平台: {}", platform_info());
    println!("用户: {}", get_username());
}

常见问题 ​

问题一:target 依赖在非目标平台上会被下载吗?

不会。Cargo 只会下载和编译当前目标平台匹配的条件依赖。交叉编译时,Cargo 根据 --target 参数判断。

问题二:cfg 条件写错了 Cargo 会报错吗?

cfg 表达式的语法错误会被 Cargo 检测到。但如果写了一个合法但永远不会匹配的条件(如 target_os = "typo"),Cargo 不会警告。

问题三:条件依赖和 features 可以组合吗?

可以。条件依赖也支持所有标准的依赖选项,包括 features、optional、default-features 等。

问题四:怎么查看当前平台支持哪些 cfg 值?

运行 rustc --print cfg 查看当前平台的所有 cfg 标志。交叉编译时用 rustc --target x86_64-unknown-linux-gnu --print cfg。

适用场景 ​

  • 跨平台项目:不同 OS 使用不同的系统 API 库
  • 架构优化:x86-64 上使用 SIMD 库
  • 嵌入式开发:针对特定目标的依赖
  • WebAssembly:wasm32 专用的绑定库

注意事项 ​

  • cfg 表达式必须用单引号包裹在 TOML 中
  • 条件依赖不会在非匹配平台上编译
  • 代码中要用对应的 #[cfg(...)] 配合使用
  • rustc --print cfg 查看可用的 cfg 标志
  • all()、any()、not() 可以组合复杂条件
  • 条件依赖同样支持 features、optional 等选项

总结 ​

条件依赖通过 [target.'cfg(...)'.dependencies] 语法声明平台相关的依赖,只在匹配的目标平台上编译和链接。cfg 表达式支持 windows、unix、target_os、target_arch 等条件,以及 all()、any()、not() 逻辑组合。条件依赖同样适用于 dev-dependencies 和 build-dependencies。代码中需要用 #[cfg(...)] 配合条件编译。rustc --print cfg 可以查看当前平台的所有 cfg 标志。