入门 The Cargo Team 2026-09-13 15:48:22 · 0 阅读

第35章 cargo build 详解

名称

cargo-build — 编译当前包

用法

cargo build [选项]

描述

编译本地包及其所有依赖项。

选项

包选择

如果未指定包选择选项，则根据选定的 manifest 文件（若未指定 --manifest-path，则基于当前工作目录）来决定要编译哪些包。若该 manifest 是 workspace 的根，则选中 workspace 的默认成员；否则，仅选中由该 manifest 定义的那个包。

可以通过在根 manifest 中设置 workspace.default-members 键来显式定义 workspace 的默认成员。若未设置此键，虚拟 workspace（virtual workspace）将包含所有成员（等效于传入 --workspace），而非虚拟 workspace（non-virtual workspace）则仅包含根 crate。

-p spec…
--package spec…: 仅构建指定的包。SPEC 格式请参见 cargo-pkgid(1)。此标志可多次指定，并支持 *、? 和 [] 等常见的 Unix 通配符模式。但为了避免 Shell 在 Cargo 处理之前意外扩展这些模式，请使用单引号或双引号将每个模式括起来。
--workspace: 构建 workspace 中的所有成员。
--all: --workspace 的弃用别名。
--exclude SPEC…: 排除指定的包。必须配合 --workspace 标志使用。该标志可多次指定，支持常见的 Unix 通配符模式，如 *、? 和 []。为防止 Shell 在 Cargo 处理前意外展开通配符，每个模式必须用单引号或双引号括起来。

目标选择

若未指定目标选择选项，cargo build 将构建所选包的所有二进制目标和库目标。如果二进制目标缺少其声明的 required-features，则会被跳过。

若选择了集成测试或基准测试进行构建，会自动构建相应的二进制目标。这使得集成测试可以执行该二进制文件以验证其行为。在构建和运行集成测试时，会设置 CARGO_BIN_EXE_<name> 环境变量，以便测试使用 env 宏或 var 函数定位可执行文件。

传入目标选择标志后，仅构建指定的目标。

注意，--bin、--example、--test 和 --bench 标志也支持常见的 Unix 通配符模式，如 *、? 和 []。为防止 Shell 在 Cargo 处理前意外展开通配符，每个模式必须用单引号或双引号括起来。

--lib: 构建包的库目标。
--bin name…: 构建指定的二进制目标。该标志可多次指定，支持常见的 Unix 通配符模式。
--bins: 构建所有二进制目标。
--example name…: 构建指定的示例。此选项可多次使用，并支持常见的 Unix 通配符模式。
--examples: 构建所有示例目标。
--test name…: 构建指定的集成测试。此选项可多次使用，并支持常见的 Unix 通配符模式。
--tests: 构建所有设置了 test = true 清单标志的目标。默认包括作为单元测试构建的库和二进制文件，以及集成测试。注意这也会构建所需的依赖项，因此 lib 目标可能会被构建两次（一次作为单元测试，一次作为二进制文件、集成测试等的依赖）。可以通过在清单中对目标设置 test 标志来启用或禁用目标。
--bench name…: 构建指定的基准测试。此选项可多次使用，并支持常见的 Unix 通配符模式。
--benches: 构建所有在 manifest 中设置了 bench = true 标志的目标。默认情况下，这包括作为基准测试构建的库、二进制文件以及 bench 目标。注意，这也构建所需的依赖项，因此 lib 目标可能会被构建两次（一次作为基准测试，另一次作为二进制文件、基准测试等的依赖项）。可通过在目标配置中设置 bench 标志来启用或禁用目标。
--all-targets: 构建所有目标。这等效于指定 --lib --bins --tests --benches --examples。

Feature Selection

功能标志用于控制启用的功能。如果没有指定任何功能选项，则默认会激活所选每个包的 default 功能。

更多详情参见功能文档。

-F features
--features features: 以空格或逗号分隔的列表，指定要激活的功能。工作区成员的功能可以使用 package-name/feature-name 语法启用。此标志可以多次指定，以启用所有指定的功能。
--all-features: 激活所选包的所有可用功能。
--no-default-features: 不激活所选包的 default 功能。

编译选项

--target triple

为指定的目标架构构建。该标志可多次指定，默认值为宿主机架构。三元组的一般格式为 <arch><sub>-<vendor>-<sys>-<abi>。

可能的取值包括：

rustc --print target-list 中列出的任何受支持目标。
"host-tuple"，它会在内部被替换为宿主机的目标。这在交叉编译某些 crate 时特别有用，可以避免将宿主机机器指定为目标（例如，在一个由多种宿主机共同开发的共享项目中，用于构建 xtask 的情况）。
指向自定义目标规范的路径。更多信息请参阅自定义目标查找路径。

也可以通过 build.target 配置值来指定此设置。

请注意，指定此标志会使 Cargo 进入不同模式，其中目标产物将放置在单独的目录中。更多详细信息请参阅构建缓存文档。

-r

--release

使用 release profile 构建优化后的产物。另请参阅 --profile 选项，以通过名称选择特定 profile。

--profile name

使用给定的 profile 进行构建。有关 profile 的更多详细信息，请参阅参考手册。

--timings

输出每次编译的耗时信息，并跟踪一段时间内的并发情况。

构建结束后会在 target/cargo-timings 目录下生成一个 cargo-timing.html 文件。另外还会生成一个文件名带时间戳的报告，方便你查看之前某次的运行结果。这些报告仅供人工查看，不提供机器可读的计时数据。

输出选项

--target-dir directory

存放所有生成产物和中间文件的目录。也可以通过 CARGO_TARGET_DIR 环境变量或 build.target-dir 配置项来指定。默认为 workspace 根目录下的 target。

--artifact-dir directory

将最终产物复制到该目录。

此选项目前不稳定，仅在 nightly 渠道可用，且需要加上 -Z unstable-options 标志才能启用。详见 https://github.com/rust-lang/cargo/issues/6790。

显示选项

-v

--verbose

使用详细输出。指定两次可获得“非常详细”的输出，其中包含额外信息，如依赖警告和构建脚本的输出。也可以通过 term.verbose 配置项来设置。

-q

--quiet

不打印 cargo 日志消息。也可通过 term.quiet 配置项指定。

--color when

控制何时使用彩色输出。有效值如下：

auto（默认）：自动检测终端是否支持彩色显示。
always：始终显示彩色。
never：从不显示彩色。

也可通过 term.color 配置项指定。

--message-format fmt

诊断消息的输出格式。可多次指定，多个值以逗号分隔。有效值如下：

human（默认）：以人类可读的文本格式显示。与 short 和 json 冲突。
short：输出简短的人类可读文本消息。与 human 和 json 冲突。
json：向标准输出发送 JSON 消息。详见参考文档。与 human 和 short 冲突。
json-diagnostic-short：确保 JSON 消息中的 rendered 字段包含 rustc 的“短”渲染结果。不能与 human 或 short 同时使用。
json-diagnostic-rendered-ansi：确保 JSON 消息中的 rendered 字段包含嵌入的 ANSI 颜色代码，以遵循 rustc 的默认颜色方案。不能与 human 或 short 同时使用。
json-render-diagnostics：指示 Cargo 不要在 JSON 消息中包含 rustc 的调试信息，而是由 Cargo 自身渲染来自 rustc 的 JSON 调试信息。Cargo 自己的 JSON 调试信息以及来自 rustc 的其他信息仍会输出。不能与 human 或 short 一起使用。

Manifest Options

--manifest-path path

指定 Cargo.toml 文件的路径。默认情况下，Cargo 会在当前目录或任何父目录中搜索 Cargo.toml 文件。

--ignore-rust-version

忽略包中的 rust-version 指定。

--locked

断言所使用的依赖项及其版本与最初生成现有 Cargo.lock 文件时完全一致。如果出现以下任一情况，Cargo 将报错退出：

缺少 lock 文件。
Cargo 因依赖解析结果不同而试图修改 lock 文件。

该选项可用于需要确定性构建的环境，例如 CI 流水线。

--offline

阻止 Cargo 因任何原因访问网络。如果没有此标志，当 Cargo 需要访问网络但网络不可用时，它会停止并报错。使用此标志后，如果可能，Cargo 会尝试在无网络的情况下继续执行。

注意，这可能导致与在线模式不同的依赖解析结果。Cargo 只会使用已下载到本地的 crate，即使本地索引显示有更新的版本也不会使用。如需在离线前下载依赖，请参阅 cargo-fetch(1) 命令。

也可以通过 net.offline 配置项来指定。

--frozen

等同于同时指定 --locked 和 --offline。

通用选项

+toolchain

如果 Cargo 是通过 rustup 安装的，且 cargo 的第一个参数以 + 开头，它会被解释为 rustup 工具链名称（例如 +stable 或 +nightly）。有关工具链覆盖机制的更多信息，请参阅 rustup 文档。

--config KEY=VALUE 或 PATH

覆盖 Cargo 的配置值。参数应采用 KEY=VALUE 形式的 TOML 语法，或者提供一个额外配置文件的路径。此参数可以多次指定。更多信息请参阅命令行覆盖一节。

-C PATH

在执行任何指定操作之前切换当前工作目录。这会影响 Cargo 默认查找项目清单（Cargo.toml）的位置，以及搜索 .cargo/config.toml 的目录等。该选项必须放在命令名之前，例如 cargo -C path/to/my-project build。

此选项仅在 nightly channel 上可用，并需要通过 -Z unstable-options 标志来启用（参见 #10098）。

-h

--help

打印帮助信息。

-Z flag

Cargo 的不稳定（仅限 nightly）标志。运行 cargo -Z help 查看详情。

其他选项

-j N

--jobs N

要运行的并行任务数量。也可以通过 build.jobs 配置值进行指定。默认值为逻辑 CPU 数量。如果为负值，则并行任务的最大数量设为逻辑 CPU 数量加上提供的值。如果提供字符串 default，则恢复默认值。不应设为 0。

--keep-going

尽可能构建依赖图中的所有 crate，而不是在第一个构建失败时中止构建。

例如，如果当前包依赖于 fails 和 works 两个依赖项，且其中一个构建失败，cargo build -j1 可能会也可能不会构建成功的那个（取决于 Cargo 选择先运行这两个构建中的哪一个），而 cargo build -j1 --keep-going 则确定会运行两个构建，即使先运行的那个失败了。

--future-incompat-report