奇链 奇链
← 教程库 / Cargo 手册
入门 The Cargo Team 2026-09-13 15:48:21 · 0 阅读

第20章 Cargo 环境变量详解

Cargo 会设置并读取一系列环境变量，你的代码可以检测或覆盖它们。以下是 Cargo 设置的环境变量列表，按其与变量交互的时机分类：

Cargo 读取的环境变量

你可以覆盖这些环境变量来改变 Cargo 在系统中的行为：

  • CARGO_LOG — Cargo 使用 tracing crate 来显示调试日志消息。CARGO_LOG 环境变量可用于启用调试日志，取值可以是 trace、debug 或 warn。通常仅在调试时使用。更多详情请参考调试日志。
  • CARGO_HOME — Cargo 维护注册表索引和 crates git 签出的本地缓存。默认情况下，这些内容存储在 $HOME/.cargo 目录下（在 Windows 上为 %USERPROFILE%\.cargo），但此变量可以覆盖该目录的位置。一旦某个 crate 被缓存，clean 命令不会将其移除。更多详情请参考指南。
  • CARGO_TARGET_DIR — 存放所有生成产物的位置，相对于当前工作目录。关于通过配置设置的说明，请参阅 build.target-dir。
  • CARGO — 如果设置了该变量，Cargo 在构建 crates、执行构建脚本和外部子命令时，将转发此值，而不是设置其自动检测到的路径。该值不会被 Cargo 直接执行，且应始终指向一个行为与 cargo 完全一致的命令，因为使用该变量的用户会这样期望。
  • RUSTC — 不再运行 rustc，而是执行指定的编译器。关于通过配置设置的说明，请参阅 build.rustc。
  • RUSTC_WRAPPER — 不再直接运行 rustc，而是执行指定的 wrapper 程序。Cargo 会将 rustc 的完整调用作为命令行参数传入，其中第一个参数是实际 rustc 可执行文件的路径。该变量常用于配置 sccache 等构建缓存工具。可通过配置项 build.rustc-wrapper 进行设置。若将其设为空字符串，将覆盖配置文件中的设置，使 Cargo 停止使用 wrapper。
  • RUSTC_WORKSPACE_WRAPPER — 针对工作区成员，Cargo 不再直接运行 rustc，而是执行指定的 workspace wrapper 程序。同样，它将 rustc 的完整调用作为命令行参数传入，第一个参数为实际 rustc 可执行文件的路径。若构建的是不含工作区的单包项目，该项目即被视为工作区。此设置会影响文件名哈希，从而使 wrapper 生成的产物独立缓存。可通过配置项 build.rustc-workspace-wrapper 进行设置。若将其设为空字符串，将覆盖配置文件中的设置，使 Cargo 停止对 工作区 成员使用 wrapper。若同时设置了 RUSTC_WRAPPER 和 RUSTC_WORKSPACE_WRAPPER，它们将被嵌套使用：最终的调用形式为 $RUSTC_WRAPPER $RUSTC_WORKSPACE_WRAPPER $RUSTC。
  • RUSTDOC — 不再直接运行默认的 rustdoc，而是执行指定的该变量所指向的 rustdoc 实例。可通过配置项 build.rustdoc 进行设置。
  • RUSTDOCFLAGS — 以空格分隔的自定义标志列表，用于传递给 Cargo 执行的所有 rustdoc 调用。与 cargo rustdoc 相比，该变量更适合向 所有 rustdoc 实例传递标志。关于更多设置标志的方式，请参见 build.rustdocflags。该字符串按空白字符分割；如需更稳健地编码多个参数，请参见 CARGO_ENCODED_RUSTDOCFLAGS。
  • CARGO_ENCODED_RUSTDOCFLAGS — 由 0x1f（ASCII Unit Separator，单元分隔符）分隔的自定义标志列表，用于传递给 Cargo 执行的所有 rustdoc 调用。
  • RUSTFLAGS — 以空格分隔的自定义 flags 列表，Cargo 会把它传给所有编译器调用。与 cargo rustc 不同，这个变量可以把 flag 传给所有编译器实例。设置 flag 的其他方式可参考 build.rustflags。该字符串按空白字符拆分；如需更可靠地传递多个参数，请使用 CARGO_ENCODED_RUSTFLAGS。
  • CARGO_ENCODED_RUSTFLAGS — 以 0x1f（ASCII 单元分隔符）分隔的自定义 flags 列表，Cargo 会把它传给所有编译器调用。
  • CARGO_INCREMENTAL — 设为 1 时，Cargo 会强制在当前编译中启用增量编译；设为 0 时则强制禁用。若未设置该变量，则使用 cargo 的默认行为。另见 build.incremental 配置项。
  • CARGO_CACHE_RUSTC_INFO — 设为 0 时，Cargo 不会缓存编译器版本信息。
  • HTTPS_PROXY、https_proxy 或 http_proxy — 要使用的 HTTP 代理，详见 http.proxy。
  • HTTP_TIMEOUT — HTTP 超时时间（秒），详见 http.timeout。
  • TERM — 设为 dumb 时禁用进度条。
  • BROWSER — 用于 cargo doc 的 --open 参数打开文档的浏览器，详见 doc.browser。
  • RUSTFMT — 设置后，cargo fmt 会执行该变量指定的 rustfmt 实例，而不是默认的 rustfmt。

    • 配置相关的环境变量

    Cargo 可以从环境变量读取部分配置值， 详情参见配置章节。 支持的环境变量汇总如下：

    Cargo 为 crate 设置的环境变量

    Cargo 在编译时将向你的 crate 暴露这些环境变量。 注意，使用 cargo run 和 cargo test 运行二进制文件时也适用。要在 Rust 程序中获取这些变量的值，可以这样做：

    let version = env!("CARGO_PKG_VERSION");

    version 将包含 CARGO_PKG_VERSION 的值。

    注意：如果 manifest 中缺少某个值，对应的环境变量会被设为空字符串 ""。

    • CARGO — 执行构建的 cargo 二进制文件的路径。
    • CARGO_MANIFEST_DIR — 包含包 manifest 的目录。
    • CARGO_MANIFEST_PATH — 包 manifest 的路径。
    • CARGO_PKG_VERSION — 包的完整版本号。
    • CARGO_PKG_VERSION_MAJOR — 包的主版本号。
    • CARGO_PKG_VERSION_MINOR — 包的次版本号。
    • CARGO_PKG_VERSION_PATCH — 包的修订版本号。
    • CARGO_PKG_VERSION_PRE — 包的预发布版本号。
    • CARGO_PKG_AUTHORS — 来自包 manifest 的作者列表，以冒号分隔。
    • CARGO_PKG_NAME — 包名称。
    • CARGO_PKG_DESCRIPTION — 来自包 manifest 的描述。
    • CARGO_PKG_HOMEPAGE — 来自包 manifest 的主页。
    • CARGO_PKG_REPOSITORY — 来自包 manifest 的仓库。
    • CARGO_PKG_LICENSE — 来自包 manifest 的许可证。
    • CARGO_PKG_LICENSE_FILE — 来自包 manifest 的许可证文件。
    • CARGO_PKG_RUST_VERSION — 来自包 manifest 的 Rust 版本。 注意：这是包支持的最低 Rust 版本，而非当前 Rust 版本。
    • CARGO_PKG_README — 包 README 文件的路径。
    • CARGO_CRATE_NAME — 当前正在编译的 crate 名称。它是将 Cargo 目标 名称中的 - 转换为 _ 后的结果，例如库、二进制文件、示例、集成测试或基准测试的名称。
    • CARGO_BIN_NAME — 当前正在编译的二进制文件名称。 仅对 二进制文件或二进制示例有效。该名称不包含任何文件扩展名（如 .exe）。
    • OUT_DIR — 如果该包有构建脚本，此变量指向构建脚本存放输出文件的目录。详见下文。（仅在编译时设置。）Cargo 不保证该目录为空，也不会在构建之间清理它。
    • CARGO_BIN_EXE_<name> — 二进制目标可执行文件的绝对路径。仅在构建集成测试或基准测试时设置。可以配合 env 宏找到需要运行的可执行文件用于测试。<name> 是二进制目标的名称，原样保留。例如，名为 my-program 的二进制对应 CARGO_BIN_EXE_my-program。构建测试时会自动构建这些二进制，除非它们依赖未启用的 feature。
    • CARGO_PRIMARY_PACKAGE — 当被构建的包是“主包”时设置此变量。主包指用户在命令行上选择的包（通过 -p 参数，或基于当前目录和默认 workspace 成员的默认值）。构建依赖时不会设置该变量，除非该依赖同时也是命令行中选中的 workspace 成员。此变量仅在编译包时设置（运行二进制或测试时不设置）。
    • CARGO_TARGET_TMPDIR — 仅在构建集成测试或基准测试代码时设置。它指向 target 目录下的一个子目录，集成测试和基准测试可以自由地把测试所需的数据放在这里。Cargo 只负责创建这个目录，不会以任何方式管理其内容，这由测试代码自行负责。

    动态库路径

    Cargo 在通过 cargo run 和 cargo test 等命令编译和运行二进制时，也会设置动态库路径，用于定位构建产物中的共享库。变量名因平台而异：

    • Windows：PATH
    • macOS：DYLD_FALLBACK_LIBRARY_PATH
    • Unix：LD_LIBRARY_PATH
    • AIX：LIBPATH

    Cargo 启动时会在现有值的基础上扩展该路径。macOS 有特殊处理：如果 DYLD_FALLBACK_LIBRARY_PATH 尚未设置，系统将自动添加默认路径 $HOME/lib:/usr/local/lib:/usr/lib。

    Cargo 会包含以下路径：

    • 通过 rustc-link-search 指令 包含在构建脚本中的搜索路径。位于 target 目录之外的路径会被移除。如果搜索路径需要包含系统上的额外库，由运行 Cargo 的用户负责正确设置环境变量。
    • 基础输出目录（例如 target/debug）及其下的 “deps” 目录。这主要用于支持 proc-macros。
    • rustc sysroot 库路径。这对大多数用户来说通常无关紧要。

    Cargo 为构建脚本设置的环境变量

    Cargo 在运行构建脚本时会设置若干环境变量。由于这些变量在编译构建脚本时尚未设置，上述使用 env! 的示例将无效，你必须在构建脚本运行时获取这些值：

    use std::env;
let out_dir = env::var("OUT_DIR").unwrap();

    此时，out_dir 将包含 OUT_DIR 的值。

    • CARGO — 执行构建的 cargo 二进制文件路径。
    • CARGO_MANIFEST_DIR — 包含当前构建包清单文件的目录（即包含该构建脚本的包）。注意，这也是构建脚本启动时的工作目录。
    • CARGO_MANIFEST_PATH — 包清单文件的路径。
    • CARGO_MANIFEST_LINKS — 清单中 links 字段的值。
    • CARGO_MAKEFLAGS — 包含用于 Cargo jobserver 实现并行化子进程所需的参数。build.rs 中调用的 rustc 或 cargo 已能读取 CARGO_MAKEFLAGS，但 GNU Make 要求通过直接传参或设置 MAKEFLAGS 环境变量来指定这些标志。目前 Cargo 不会设置 MAKEFLAGS 变量，但调用 GNU Make 的构建脚本可以自由将其设为 CARGO_MAKEFLAGS 的内容。
    • CARGO_FEATURE_<name> — 对于正在构建的包中每个启用的 feature，若 <name> 是该 feature 名称的大写形式且将 - 替换为 _，则对应环境变量存在。
    • CARGO_CFG_<cfg> — 对于正在构建的包中每个配置项，该环境变量包含对应配置的值，其中 <cfg> 是配置名称的大写形式且将 - 替换为 _。布尔型配置项在设置时存在，否则不存在。多值配置项通过 , 分隔合并到单个变量中。这包括编译器内置的值（可通过 rustc --print=cfg 查看），以及由构建脚本和传递给 rustc 的额外标志（如 RUSTFLAGS 中定义的值）设置的值。这些变量的一些示例如下：

      注意，不同的目标三元组（target triple）对应不同的 cfg 值集合，某个目标三元组中存在的变量，在另一个中可能并不存在。

      类似 test 这样的 cfg 值是不可用的。

      提示：如果想用类型安全的方式读取这些值，可以考虑使用 build-rs crate，而不是手动解析环境变量。另外请注意，在构建脚本中应使用 CARGO_CFG_* 变量，而不是 cfg! 宏或 #[cfg] 属性——后者检查的是 host 平台，而不是 target。

    • OUT_DIR — 存放所有输出产物和中间产物的目录。该目录位于被构建包的构建目录内，且对每个包是唯一的。Cargo 在多次构建之间不会清理或重置这个目录，其内容可能会在重新构建时保留下来。构建脚本不应假设 OUT_DIR 是空的，需要自行负责管理或清理自己创建的文件。
    • TARGET —— 目标三元组。原生代码应针对此三元组编译。有关更多详细信息，请参阅目标三元组中的说明。
    • HOST —— Rust 编译器的宿主三元组。
    • NUM_JOBS —— 顶层并行度指定的并行数量。这对于向类似 make 的系统传递 -j 参数非常有用。注意在解释此环境变量时应谨慎。出于历史原因，我们仍然提供它，但 Cargo 的近期版本不再需要运行 make -j，而是可以将 MAKEFLAGS 环境变量设置为 CARGO_MAKEFLAGS 的内容，以启用 Cargo 的 GNU Make 兼容的jobserver 用于子 make 调用。
    • DEBUG —— 如果将生成任何 debug 信息，则为 true，否则为 false。
    • OPT_LEVEL —— 当前正在构建的 profile 对应的 opt-level 变量的值。
    • PROFILE —— 对于发布构建为 release，其他构建为 debug。这是基于 profile 是否继承自 dev 或 release profile 来确定的。不建议使用此环境变量。使用 OPT_LEVEL 等其他环境变量可以提供关于实际使用设置的更准确的视角。
    • DEP_<links>_<key> —— 关于此组环境变量的更多详细信息，请参阅构建脚本文档中关于 links 的说明。
    • RUSTC、RUSTDOC —— Cargo 解析确定要使用的编译器和文档生成器，会传递给构建脚本，以便其也可使用。
    • RUSTC_WRAPPER —— 如果存在，Cargo 正在使用的 rustc 包装器。请参阅 build.rustc-wrapper。
    • RUSTC_WORKSPACE_WRAPPER —— 如果存在，Cargo 为工作区成员使用的 rustc 包装器。请参阅 build.rustc-workspace-wrapper。
    • RUSTC_LINKER — 当前目标架构解析出的链接器二进制文件路径（如果已指定）。通过编辑 .cargo/config.tom 可以更改链接器；有关更多详情，请参阅Cargo 配置文档。
    • CARGO_ENCODED_RUSTFLAGS — Cargo 调用 rustc 时使用的额外参数，各项之间以 0x1f 字符（ASCII 单元分隔符）分隔。参见 build.rustflags。注意：自 Rust 1.55 起，RUSTFLAGS 已不再存在于环境变量中，脚本应改用 CARGO_ENCODED_RUSTFLAGS。
    • CARGO_PKG_<var> — 包信息变量，其名称和值与构建 crate 时提供的完全一致。

    Cargo 为 cargo test 设置的环境变量

    运行测试时，Cargo 会设置多个环境变量。 你可以获取这些变量的值：

    use std::env;
let out_dir = env::var("CARGO_BIN_EXE_foo").unwrap();
    • CARGO_BIN_EXE_<name> — 二进制目标可执行文件的绝对路径。 仅在运行集成测试或基准测试时设置。 <name> 即二进制目标的名称，保持原样。例如，名为 my-program 的二进制对应 CARGO_BIN_EXE_my-program。 构建测试时会自动构建二进制文件，除非该二进制依赖的特性未被启用。

    Cargo 为第三方子命令设置的环境变量

    Cargo 为第三方子命令（即放置在 $PATH 中、命名为 cargo-foobar 的程序）暴露此环境变量：

    • CARGO — 执行构建的 cargo 二进制文件的路径。
    • CARGO_MAKEFLAGS — 包含用于 Cargo jobserver 实现的并行化子进程所需的参数。 仅当 Cargo 检测到 jobserver 存在时才会设置此变量。

    如需了解环境的更多详细信息，可以运行 cargo metadata。

    上一篇
    第19章 Cargo 配置详解
    下一篇
    第21章 Cargo 构建脚本详解

    本篇用到的工具

    Cargo
    Cargo
    Rust 官方的包管理器与构建工具

    评论 (0)