第36章 cargo check 命令详解

名称

cargo-check — 检查当前包

概要

cargo check [选项]

描述

检查本地包及其所有依赖项是否存在错误。这基本上是在编译包时跳过了代码生成这一步，因此比运行 cargo build 更快。编译器会将元数据文件保存到磁盘，以便在源代码未修改时供后续运行复用。由于部分诊断信息和错误仅在代码生成阶段产生，因此 cargo check 自然无法报告这些问题。

选项

包选择

默认情况下，如果未指定包选择选项，所选包取决于选定的清单文件（如果未指定 --manifest-path，则基于当前工作目录确定）。如果清单文件是工作区的根，则选择工作区的默认成员；否则，仅选择由该清单文件定义的那个包。

工作区的默认成员可以通过在根清单文件中设置 workspace.default-members 键来显式指定。如果未设置，虚拟工作区将包含所有工作区成员（等效于传入 --workspace），而非虚拟工作区则仅包含根 crate 本身。

-p spec…

--package spec…

仅检查指定的包。SPEC 格式请参考 cargo-pkgid(1)。该标志可以多次指定，并支持常见的 Unix glob 模式，如 *、? 和 []。但是，为了避免 Shell 在 Cargo 处理之前意外展开 glob 模式，每个模式必须使用单引号或双引号包裹。

--workspace

检查工作区中的所有成员。

--all

已废弃，现作为 --workspace 的别名。

--exclude SPEC…

排除指定的包。必须与 --workspace 标志配合使用。该标志可多次指定，并支持常见的 Unix 通配符模式（如 *、? 和 []）。为防止 Shell 在 Cargo 处理之前意外展开通配符，务必用单引号或双引号包裹每个模式。

目标选择

若未提供目标选择选项，cargo check 将检查所选包的所有二进制文件和库目标。如果二进制文件缺失必需的 required-features，则会跳过它们。

传入目标选择标志后，仅检查指定的目标。

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

--lib

检查包的库目标。

--bin name…

检查指定的二进制目标。该标志可多次指定，并支持常见的 Unix 通配符模式。

--bins

检查所有二进制目标。

--example name…

检查指定的示例。该参数可以多次指定，并支持常见的 Unix glob 模式。

--examples

检查所有示例目标。

--test name…

检查指定的集成测试。该参数可以多次指定，并支持常见的 Unix glob 模式。

--tests

检查所有在清单中设置了 test = true 标志的目标。默认包括作为单元测试构建的库和二进制文件，以及集成测试。注意这也会构建所有必需的依赖项，因此库目标可能会被构建两次（一次作为单元测试，一次作为二进制文件、集成测试等的依赖）。可以通过在清单设置中为目标设置 test 标志来启用或禁用目标。

--bench name…

检查指定的基准测试。该参数可以多次指定，并支持常见的 Unix glob 模式。

--benches

检查所有在清单中设置了 bench = true 标志的目标。默认包括作为基准测试构建的库和二进制文件，以及 bench 目标。注意这也会构建所有必需的依赖项，因此库目标可能会被构建两次（一次作为基准测试，一次作为二进制文件、基准测试等的依赖）。可以通过在清单设置中为目标设置 bench 标志来启用或禁用目标。

--all-targets

检查所有目标。这等价于同时指定 --lib --bins --tests --benches --examples。

功能选择

功能标志（feature flags）用于控制启用哪些功能。如果未指定任何功能选项，将为每个选定的包激活 default 功能。

有关更多详细信息，请参见 功能文档。

-F features

--features features

以空格或逗号分隔的功能列表，用于激活指定功能。工作区成员的功能可以使用 package-name/feature-name 语法启用。此标志可以指定多次，从而启用所有指定的功能。

--all-features

激活所有选定包中可用的所有功能。

--no-default-features

不激活选定包的 default 功能。

编译选项

--target triple

针对指定的目标架构进行检查。该标志可以指定多次。默认值为宿主架构。三元组（triple）的一般格式为 <arch><sub>-<vendor>-<sys>-<abi>。

可能的值：

• rustc --print target-list 中支持的任意目标。
• "host-tuple"，该值会被内部替换为宿主机的 target。在进行交叉编译某些 crate 时，此选项尤其有用——如果你不希望将宿主机本身指定为 target（例如在多人协作的项目中，需要被不同宿主机运行的共享 xtask），就可以用它。
• 自定义 target 规范文件的路径。更多信息请参考Custom Target Lookup Path。

也可以通过配置项 build.target 的config 值来指定。

请注意，指定该选项会使 Cargo 进入不同的运行模式，其中 target 产物会被放置到单独的目录中。更多详情请参阅build cache文档。

-r

--release

使用 release profile 检查优化后的产物。如需按名称选择特定 profile，也可参考 --profile 选项。

--profile name

使用指定的 profile 进行检查。

特殊情况：指定 test profile 时，会同时启用 test 模式的检查，这会开启对测试的检查并启用 test cfg 选项。更多细节请参阅rustc tests。

关于 profile 的更多细节，请参阅参考文档。

--timings

输出每个编译步骤耗时的信息，并跟踪随时间变化的并发情况。

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

输出选项

--target-dir directory

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

显示选项

-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：向 stdout 输出 JSON 消息。详见参考文档。与 human 和 short 互斥。
• json-diagnostic-short：确保 JSON 消息中的 rendered 字段包含来自 rustc 的“short”渲染结果。不能与 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 选项

--manifest-path path

Cargo.toml 文件的路径。默认情况下，Cargo 会在当前目录或其任意父目录中查找 Cargo.toml。

--ignore-rust-version

忽略包中的 rust-version 声明。

--locked

强制使用生成现有 Cargo.lock 文件时的确切依赖项及版本。遇到以下任一情况时，Cargo 将报错退出：

• 锁文件缺失。
• 因依赖解析方式不同，Cargo 试图修改锁文件。

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

--offline

禁止 Cargo 因任何原因访问网络。未使用此标志时，若 Cargo 需要访问网络但网络不可用，它将报错停止；使用此标志后，若可能，Cargo 将尝试在不联网的情况下继续执行。

注意：这可能导致依赖解析结果与在线模式不同。Cargo 将仅使用本地已下载的 crate，即使本地索引副本中显示存在更新版本。建议在离线前使用 cargo-fetch(1) 命令下载依赖项。

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

--frozen

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

Common Options

+toolchain

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

--config KEY=VALUE 或 PATH

覆盖 Cargo 的配置项。参数应使用 TOML 语法的 KEY=VALUE 形式，或提供额外配置文件的路径。此标志可多次指定。详见命令行覆盖一节。

-C PATH

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

此选项仅在 nightly 渠道可用，且需启用 -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 两个 crate，其中 fails 构建失败。执行 cargo check -j1 时，可能构建也可能不构建成功的那个（取决于 Cargo 先调度哪一个），而 cargo check -j1 --keep-going 则一定会尝试构建两者，即使先执行的那个失败了。

--future-incompat-report

针对执行该命令期间产生的未来不兼容警告，显示未来不兼容报告。

详见 cargo-report(1)

ENVIRONMENT

有关 Cargo 读取的环境变量详情，请参见参考文档。

EXIT STATUS

• 0：Cargo 执行成功。
• 101：Cargo 执行失败。

EXAMPLES

1. 检查本地包是否存在错误：

   cargo check
   

2. 检查所有目标，包括单元测试：

   cargo check --all-targets --profile=test
   

SEE ALSO

cargo(1)、cargo-build(1)