• 开发工具
• 包管理器
• CLI
• 构建工具

本文系统梳理 Rust 包管理器 Cargo 与环境变量的全部交互：Cargo 读取哪些变量来改变自身行为、编译 crate 时注入了哪些变量、build script（构建脚本）运行时会获得哪些专属变量。读者读完可以掌握CARGO_HOME、RUSTFLAGS、CARGO_CFG_*、CARGO_FEATURE_*、OUT_DIR等核心变量的语义、优先级与在build.rs与测试代码中的读取姿势，并理解 Cargo 在 src/context/environment.rs 中实现的环境变量快照机制。

背景：man 手册中的 ENVIRONMENT 片段从哪里来

本主题源自 Cargo 仓库的 man 文档片段 doc/man/includes/section-environment.md，它只有短短两行：

## ENVIRONMENT See the reference for details on environment variables that Cargo reads.

这个片段由 mdman 模板系统嵌入到36 个cargo-*子命令的 man 页面中（如 doc/man/cargo-build.md、doc/man/cargo-test.md、doc/man/cargo-run.md 等均以{{> section-environment }}方式引入），统一指向手册参考章节 doc/book/src/reference/environment-variables.md。也就是说，任何子命令的--help/ man 文档都会提示读者："Cargo 读取哪些环境变量，详见参考手册"。本文即对该参考手册的完整展开，并结合仓库源码逐项印证。

参考手册将环境变量按Cargo 何时与之交互分为五类：

1. Cargo 读取（用户可覆盖，改变 Cargo 行为）；
2. Cargo 为 crate（编译期）设置；
3. Cargo 为 build script 设置；
4. Cargo 为cargo test设置；
5. Cargo 为第三方子命令设置。

下面按此脉络逐一深入。

Cargo 读取的环境变量：你可以覆盖哪些行为

这些变量可以在你的系统环境中设置，从而改变 Cargo 的默认行为。它们大多同时存在对应的.cargo/config.toml配置键，且环境变量优先级高于 TOML 配置文件（详见 doc/book/src/reference/config.md 的 "Environment variables" 一节）。

日志、缓存与产物目录

在源码层，CARGO_TARGET_DIR的读取逻辑位于 src/context/mod.rs：GlobalContext::target_dir()依次检查命令行--target-dir、环境变量CARGO_TARGET_DIR（空字符串会被明确拒绝并报错）、build.target_dir配置项。

编译器与 rustdoc 替换

编译标志：RUSTFLAGS 与 CARGO_ENCODED_RUSTFLAGS

注意：自 Rust 1.55 起，RUSTFLAGS会从 build script 的环境中移除，脚本应改用CARGO_ENCODED_RUSTFLAGS。源码中 build script 环境的确如此处理：见 src/compiler/custom_build.rs，先设置CARGO_ENCODED_RUSTFLAGS（用"\x1f"连接），随后env_remove("RUSTFLAGS")。

网络与显示相关

配置类环境变量：CARGO_* 与 config 键的映射规则

Cargo 允许通过环境变量覆盖绝大多数配置项。规则见 doc/book/src/reference/config.md：对形如foo.bar的配置键，可用环境变量CARGO_FOO_BAR定义。键转大写、点与短横线转下划线。例如配置键target.x86_64-unknown-linux-gnu.runner对应CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_RUNNER。

优先级：--config 高于环境变量高于配置文件

• --config命令行参数 > 环境变量 > TOML 配置文件（见 doc/book/src/reference/config.md）。
• 目前仅支持整数、布尔、字符串与部分数组类型通过环境变量定义。

源码中的实现：Env 快照与大小写归一化

Cargo 在启动时对进程环境做一次性快照，实现位于 src/context/environment.rs 的make_case_insensitive_and_normalized_env：

• case_insensitive_env：将所有键转为大写映射回真实键，用于 Windows 上键大小写不敏感的环境；
• normalized_env：保留 UTF-8 键值对，把键转大写并将-替换为_，用于配置系统告警提示（例如用户写成CARGO_BUILD-RUSTC时会收到错误格式提示）。

配置值的读取则经由GlobalContext::get的 Typed Config Value API，仅支持CARGO_前缀的环境键（见 src/context/environment.rs 的文档注释）。

全量清单（与 config 键一一对应）

参考手册列出的配置环境变量包括（均指向 doc/book/src/reference/config.md 对应小节）：

• alias / 构建：CARGO_ALIAS_<name>、CARGO_BUILD_WARNINGS、CARGO_BUILD_JOBS、CARGO_BUILD_RUSTC、CARGO_BUILD_RUSTC_WRAPPER、CARGO_BUILD_RUSTC_WORKSPACE_WRAPPER、CARGO_BUILD_RUSTDOC、CARGO_BUILD_TARGET、CARGO_BUILD_TARGET_DIR、CARGO_BUILD_BUILD_DIR、CARGO_BUILD_PROFILE、CARGO_BUILD_RUSTFLAGS、CARGO_BUILD_RUSTDOCFLAGS、CARGO_BUILD_INCREMENTAL、CARGO_BUILD_DEP_INFO_BASEDIR；
• 缓存 / 新建项目 / 凭据：CARGO_CACHE_AUTO_CLEAN_FREQUENCY、CARGO_CARGO_NEW_VCS、CARGO_CREDENTIAL_ALIAS_<name>、CARGO_FUTURE_INCOMPAT_REPORT_FREQUENCY；
• HTTP：CARGO_HTTP_DEBUG、CARGO_HTTP_PROXY、CARGO_HTTP_TIMEOUT、CARGO_HTTP_CAINFO、CARGO_HTTP_PROXY_CAINFO、CARGO_HTTP_CHECK_REVOKE、CARGO_HTTP_SSL_VERSION、CARGO_HTTP_LOW_SPEED_LIMIT、CARGO_HTTP_MULTIPLEXING、CARGO_HTTP_USER_AGENT；
• install / net：CARGO_INSTALL_ROOT、CARGO_INSTALL_PROFILE、CARGO_NET_RETRY、CARGO_NET_GIT_FETCH_WITH_CLI、CARGO_NET_OFFLINE；
• profile：CARGO_PROFILE_<name>_BUILD_OVERRIDE_<key>、CARGO_PROFILE_<name>_CODEGEN_UNITS、CARGO_PROFILE_<name>_DEBUG、CARGO_PROFILE_<name>_DEBUG_ASSERTIONS、CARGO_PROFILE_<name>_INCREMENTAL、CARGO_PROFILE_<name>_LTO、CARGO_PROFILE_<name>_OVERFLOW_CHECKS、CARGO_PROFILE_<name>_OPT_LEVEL、CARGO_PROFILE_<name>_PANIC、CARGO_PROFILE_<name>_RPATH、CARGO_PROFILE_<name>_SPLIT_DEBUGINFO、CARGO_PROFILE_<name>_STRIP；
• registries / registry：CARGO_REGISTRIES_<name>_CREDENTIAL_PROVIDER、CARGO_REGISTRIES_<name>_INDEX、CARGO_REGISTRIES_<name>_MIN_PUBLISH_AGE、CARGO_REGISTRIES_<name>_TOKEN、CARGO_REGISTRIES_CRATES_IO_PROTOCOL、CARGO_REGISTRY_CREDENTIAL_PROVIDER、CARGO_REGISTRY_DEFAULT、CARGO_REGISTRY_GLOBAL_CREDENTIAL_PROVIDERS、CARGO_REGISTRY_GLOBAL_MIN_PUBLISH_AGE、CARGO_REGISTRY_TOKEN；
• resolver：CARGO_RESOLVER_INCOMPATIBLE_PUBLISH_AGE、CARGO_RESOLVER_INCOMPATIBLE_RUST_VERSIONS、CARGO_RESOLVER_LOCKFILE_PATH；
• target：CARGO_TARGET_<tuple>_LINKER、CARGO_TARGET_<tuple>_RUNNER、CARGO_TARGET_<tuple>_RUSTFLAGS、CARGO_TARGET_<tuple>_RUSTDOCFLAGS（tuple 需转为大写与下划线）；
• term：CARGO_TERM_QUIET、CARGO_TERM_VERBOSE、CARGO_TERM_COLOR、CARGO_TERM_HYPERLINKS、CARGO_TERM_UNICODE、CARGO_TERM_PROGRESS_WHEN、CARGO_TERM_PROGRESS_WIDTH、CARGO_TERM_PROGRESS_TERM_INTEGRATION。

补充：CARGO_HOME 的目录结构

CARGO_HOME不仅是缓存根目录，还包含 Cargo 的全局配置与安装产物。按 doc/book/src/guide/cargo-home.md 所述：

• 文件：config.toml（全局配置）、credentials.toml（cargo login写入的私密凭据）、.crates.toml/.crates2.json（cargo install安装的包信息，勿手工编辑）；
• 目录：bin/（cargo install与 rustup 安装的可执行文件，需加入$PATH）、git/db/（git 依赖的裸仓库）、git/checkouts/（git 依赖检出目录）、registry/index/（注册表索引的裸 git 仓库）、registry/cache/（下载的.crategzip 压缩包）、registry/src/（解压后的源码）。

在 CI 中缓存 Cargo home 时，手册建议仅缓存.crates.toml、.crates2.json、bin/、registry/index/、registry/cache/、git/db/，避免同时缓存.crate与其解压源码两份数据。源码层中git/与registry/子目录的定位见 src/context/mod.rs。

Cargo 为 crate 设置的环境变量：编译期可见

cargo run与cargo test运行二进制时同样注入这些变量。在 Rust 代码中可用env!宏在编译期读取：

let version = env!("CARGO_PKG_VERSION");

version即包含CARGO_PKG_VERSION的值。注意：若 manifest 未提供对应字段，相关变量会被设为空字符串""。

完整清单（详见 doc/book/src/reference/environment-variables.md）：

• 路径：CARGO（正在执行构建的 cargo 二进制路径）、CARGO_MANIFEST_DIR（包 manifest 所在目录）、CARGO_MANIFEST_PATH（manifest 的完整路径）；
• 包信息：CARGO_PKG_VERSION（完整版本）、CARGO_PKG_VERSION_MAJOR/MINOR/PATCH/PRE（版本段）、CARGO_PKG_AUTHORS（冒号分隔的作者列表）、CARGO_PKG_NAME、CARGO_PKG_DESCRIPTION、CARGO_PKG_HOMEPAGE、CARGO_PKG_REPOSITORY、CARGO_PKG_LICENSE、CARGO_PKG_LICENSE_FILE、CARGO_PKG_RUST_VERSION（注意是包声明的最低 Rust 版本，而非当前 rustc 版本）、CARGO_PKG_README；
• 目标信息：CARGO_CRATE_NAME（当前编译 crate 名，-转为_，适用于 lib/bin/example/集成测试/bench）、CARGO_BIN_NAME（当前编译的二进制名，不含.exe等扩展名，仅二进制目标与二进制 example 设置）；
• 构建脚本输出：OUT_DIR（若有 build script，指向其输出目录；Cargo 不保证目录为空，且两次构建间不清空）；
• 测试辅助：CARGO_BIN_EXE_<name>（集成测试或 benchmark 构建时，指向某二进制可执行文件的绝对路径，<name>为二进制目标原名，如CARGO_BIN_EXE_my-program）、CARGO_TARGET_TMPDIR（仅集成测试/benchmark 构建时设置，指向 target 目录内供测试自由使用的目录，Cargo 创建但不管理其内容）；
• 主包标记：CARGO_PRIMARY_PACKAGE（仅当包是主包时设置。主包指用户在命令行用-p选中的包或当前目录/默认 workspace 成员；编译依赖时不会设置，除非该依赖同时是被选中的 workspace 成员；且仅编译包时设置，运行二进制或测试时不设）。

源码佐证：这些变量在 src/compiler/compilation.rs 中逐一注入，CARGO_PKG_VERSION_*、CARGO_PKG_NAME、CARGO_MANIFEST_DIR、CARGO_MANIFEST_PATH均直接取自 package 对象；CARGO_BIN_NAME与CARGO_CRATE_NAME由 fill_rustc_tool_env 设置；CARGO_BIN_EXE_<name>在 src/compiler/artifact.rs 为测试构建补充（cargo check时也会提供占位值以让env!("CARGO_BIN_EXE_...")宏可编译）；CARGO_PRIMARY_PACKAGE与CARGO_TARGET_TMPDIR见 src/compiler/mod.rs。

动态库搜索路径

编译与运行（cargo run/cargo test）时，Cargo 还会扩展动态库搜索路径以定位构建过程的共享库，变量名因平台而异：

Cargo 会在启动时已有值的基础上追加以下路径：

• 任何 build script 通过rustc-link-search指令给出的搜索路径（target目录之外的路径会被移除；系统库需用户自行设置环境）；
• 基础输出目录（如target/debug）及其deps目录（主要为 proc-macro 支持）；
• rustc sysroot 库路径（一般对用户不重要）。

macOS 有特殊处理：若DYLD_FALLBACK_LIBRARY_PATH未设置，Cargo 会补上默认的$HOME/lib:/usr/local/lib:/usr/lib——对应源码 src/compiler/compilation.rs 中的逻辑。

Cargo 为 build script 设置的环境变量

build script（build.rs）运行时这些变量尚未被设置，因此不能用env!宏，必须在运行时读取：

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

out_dir即包含OUT_DIR的值。

基础信息

• CARGO：执行构建的 cargo 二进制路径；
• CARGO_MANIFEST_DIR：被构建包（含 build script 的包）的 manifest 目录，也是 build script 启动时的当前工作目录；
• CARGO_MANIFEST_PATH：包 manifest 的路径；
• CARGO_MANIFEST_LINKS：manifest 中links键的值（见 src/compiler/custom_build.rs）；
• CARGO_PKG_<var>：与编译期 variables set for crates 同名同值的包信息变量。

并行度与 jobserver

• CARGO_MAKEFLAGS：包含 Cargo jobserver 实现所需的参数，用于并行化子进程。rustc或cargo调用可直接读取；GNU Make 则要求通过MAKEFLAGS环境变量或命令行参数指定。Cargo 自身不设置MAKEFLAGS，但 build script 可自由地把CARGO_MAKEFLAGS的内容赋给它，以在子 make 中启用 Cargo 的 GNU Make 兼容 jobserver。

jobserver 在源码中的管理见 src/compiler/build_runner/mod.rs：若环境中没有外部 jobserver（gctx.jobserver_from_env()），Cargo 会创建自己的jobserver::Client；此外 src/compiler/build_config.rs 会在同时指定-j与外部 jobserver 时发出警告。

features 与 cfg

• CARGO_FEATURE_<name>：对每个已激活 feature，设置该变量，<name>为 feature 名转大写、-转_；
• CARGO_CFG_<cfg>：对每个配置项设置该变量，<cfg>为配置名转大写、-转_。布尔型配置存在即设置、不存在即不设置；多值配置用逗号连接为单变量。它包含编译器内置值（可用rustc --print=cfg查看）以及 build script 与额外rustc标志（如RUSTFLAGS）设置的值。常见示例：
  • CARGO_CFG_FEATURE— 每个已激活 feature；
  • CARGO_CFG_UNIX/CARGO_CFG_WINDOWS— Unix/Windows 平台；
  • CARGO_CFG_TARGET_FAMILY=unix,wasm、CARGO_CFG_TARGET_OS=macos、CARGO_CFG_TARGET_ARCH=x86_64、CARGO_CFG_TARGET_VENDOR=apple、CARGO_CFG_TARGET_ENV=gnu、CARGO_CFG_TARGET_ABI=eabihf、CARGO_CFG_TARGET_POINTER_WIDTH=64、CARGO_CFG_TARGET_ENDIAN=little、CARGO_CFG_TARGET_FEATURE=mmx,sse。

注意两点：

1. 不同 target tuple 的cfg值集合不同，某个 tuple 存在的变量在另一个 tuple 中可能不存在；test等部分 cfg 值不可用。
2. CARGO_CFG_*应优先于cfg!宏或#[cfg]属性在 build script 中使用，后者检查的是host平台而非target。如需类型化 API，可考虑社区build-rscrate 而非手工解析。

源码层面，CARGO_FEATURE_<name>与CARGO_CFG_<cfg>的注入在 src/compiler/custom_build.rs：feature 与 cfg 被收集进cfg_map后遍历写入，键名转换复用 src/compiler/mod.rs 的envify函数（转大写、-转_）；同时会依据 profile 设置手工注入debug_assertions，并跳过 rustc 查询中的同名值。

构建环境

• OUT_DIR：build script 所有输出与中间产物的目录，位于该包的构建目录内、对包唯一。Cargo不会在构建间清空或重置它，内容可能跨重编译保留；build script 不应假设OUT_DIR为空，需自行管理创建的文件。它仅在 build script 执行与 crate 编译期间设置，运行时不可用（对应源码 src/compiler/custom_build.rs）；
• TARGET：当前编译的目标 tuple，原生代码应针对它编译；
• HOST：rustc 编译器的 host tuple；
• NUM_JOBS：顶层并行度，可传给make -j之类的系统。注意：这是历史遗留变量，新版 Cargo 并不需要make -j，改为将MAKEFLAGS设为CARGO_MAKEFLAGS内容即可激活 jobserver 供子 make 使用；
• DEBUG：将生成任何 debug 信息时为true，否则false；
• OPT_LEVEL：当前 profile 对应opt-level的值；
• PROFILE：release 构建为release，其余为debug（依据 profile 是否继承自dev/release）。不推荐使用该变量，OPT_LEVEL等变量能更准确地反映实际设置；
• DEP_<links>_<key>：详见 build script 文档中links键的说明。

编译器上下文

• RUSTC、RUSTDOC：Cargo 解析出的编译器与文档生成器路径，供 build script 复用；
• RUSTC_WRAPPER：Cargo 正在使用的 rustc 包装器（若有）；RUSTC_WORKSPACE_WRAPPER：对 workspace 成员生效的包装器（若有）——源码中两者设置/移除逻辑见 src/compiler/custom_build.rs；
• RUSTC_LINKER：Cargo 为当前 target 解析出的链接器二进制路径（若指定），可通过.cargo/config.toml修改；
• CARGO_ENCODED_RUSTFLAGS：Cargo 调用 rustc 时附带的额外标志，以0x1f分隔；自 Rust 1.55 起RUSTFLAGS从环境中移除，脚本应改用本变量。

路径消毒（trim-paths）

• CARGO_TRIM_PATHS_SCOPE：trim-pathsprofile 选项的值。若 build script 把绝对路径引入构建产物（如调用编译器），用户可请求在各类产物中将其消毒；常见需处理的路径包括OUT_DIR、CARGO_MANIFEST_DIR、CARGO_MANIFEST_PATH及 build script 引入的其他路径（如 include 目录）。为向前兼容，build script 应接受逗号分隔的 scope 列表；
• CARGO_TRIM_PATHS_REMAP：Cargo 传给编译器的<from>=<to>路径重映射对，以平台路径分隔符连接；trim-paths为"none"时为空。build script 可把这些映射转发给 C/C++ 编译器（如通过cc的-ffile-prefix-map），使路径消毒与构建其余部分保持一致。

两者的注入见 src/compiler/custom_build.rs，CARGO_TRIM_PATHS_REMAP由trim_paths_remap计算生成。

cargo test 与第三方子命令

cargo test 专属变量

CARGO_BIN_EXE_<name>在运行集成测试或 benchmark 时设置，指向二进制目标可执行文件的绝对路径，<name>为二进制目标原名（如CARGO_BIN_EXE_my-program）；除非二进制有未启用的必需 feature，否则它会在测试构建时自动构建。运行时读取示例：

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

第三方子命令可见的变量

对放置于$PATH的第三方子命令（即名为cargo-foobar的程序），Cargo 暴露：

• CARGO：执行构建的 cargo 二进制路径；
• CARGO_MAKEFLAGS：Cargo jobserver 实现所需的参数，仅当 Cargo 检测到 jobserver 存在时才设置。

若需更全面的环境信息，可运行cargo metadata获取机器可读的项目/依赖数据。

实战小结与最佳实践

• 优先用配置键而非散落的环境变量：多数行为既有环境变量也有 config 键，配置文件更便于团队共享；环境变量适合 CI 一次性覆盖（注意其优先级高于 TOML 文件，--config又高于环境变量）。
• 给 rustc 传标志用CARGO_ENCODED_RUSTFLAGS：空格分隔的RUSTFLAGS在含引号/特殊字符时易出错，0x1f分隔更健壮，且 build script 内RUSTFLAGS已被移除。
• build script 中读 target 平台用CARGO_CFG_*：不要用cfg!/#[cfg]，它们检查的是 host。
• OUT_DIR不做清空假设：build script 需自行幂等地管理其中文件。
• 区分编译期与运行期：env!("CARGO_PKG_*")在编译期求值，CARGO_CFG_*、CARGO_FEATURE_*、OUT_DIR仅在 build script 运行时可用，运行时程序无法读取。

更多细节请继续查阅仓库内的权威来源：doc/book/src/reference/environment-variables.md（完整清单）、doc/book/src/reference/config.md（配置键与环境变量映射）、doc/book/src/guide/cargo-home.md（CARGO_HOME 结构），以及实现层 src/context/environment.rs（环境快照）、src/compiler/custom_build.rs（build script 环境注入）。

• 开发工具
• 包管理器
• CLI
• 构建工具