第32章 cargo help 命令详解

名称

cargo-help — 获取 Cargo 命令的帮助信息

概要

cargo help [子命令]

描述

打印指定命令的帮助信息。

对于包含子命令的命令，用空格分隔各级命令。例如，cargo help report future-incompatibilities 会显示 cargo report future-incompatibilities 命令的帮助信息。

空格只用于分隔父命令及其子命令之间的层级。命令名称中自带的连字符（如 generate-lockfile）必须原样保留。

多级命令也可以写成一个用连字符连接的词。例如，cargo help report-future-incompatibilities 等价于 cargo help report future-incompatibilities。

选项

显示选项

-v

--verbose

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

-q

--quiet

不打印 cargo 日志信息。也可以通过 term.quiet 配置项 设置。

--color when

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

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

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

Manifest 选项

--locked

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

• 锁文件缺失。
• 由于依赖解析结果不同，Cargo 试图修改锁文件。

适用于需要确定性构建的环境，例如 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 or PATH

覆盖 Cargo 配置值。参数需采用 KEY=VALUE 的 TOML 语法，或提供额外配置文件的完整路径。此标志可多次指定。详见命令行覆盖部分。

-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）flag。运行 cargo -Z help 查看详情。

环境变量

Cargo 读取的环境变量详见参考文档。

退出状态

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

示例

1. 查看某个命令的帮助：

   cargo help build
   

2. 查看嵌套子命令的帮助：

   cargo help report future-incompatibilities
   

3. 用短横线连接的形式也可以：

   cargo help report-future-incompatibilities
   

4. 也可以用 --help flag 获取帮助：

   cargo build --help
   

另见

cargo(1)