第53章 cargo pkgid 命令详解：打印包规格说明

名称

cargo-pkgid — 打印完整的包规格说明

概要

cargo pkgid [选项] [spec]

描述

给定一个 spec 参数，输出当前工作区中某个包或依赖的完整限定包 ID 规格。如果 spec 在依赖图中指向不明（即匹配到多个包），此命令将报错。如果未提供 spec，则输出本地包的规格。

此命令要求存在 lockfile 且依赖项已获取。

包规格说明由名称、版本和源 URL 组成。只要匹配到的包是唯一的，就可以使用部分规格说明来简洁地指定特定包。Cargo 的其他部分也会使用这种规格说明，例如 cargo-metadata(1) 以及 Cargo 输出的 JSON 消息。

spec 的格式可以是以下几种之一：

规格说明的语法规则见 包 ID 规格说明 章节。

选项

包选择

-p spec

--package spec

获取指定包的 package ID，而不是当前包的。

显示选项

-v

--verbose

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

-q

--quiet

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

--color when

控制何时使用彩色输出。可选值：

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

也可以通过 term.color 配置项设置。

清单选项

--manifest-path path

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

--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 或 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 可用）标志。运行 cargo -Z help 查看详情。

ENVIRONMENT

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

EXIT STATUS

• 0：Cargo 执行成功。
• 101：Cargo 未能完成执行。

EXAMPLES

1. 获取 foo 包的包标识符：

   cargo pkgid foo
   

2. 获取 foo 1.0.0 版本的包标识符：

   cargo pkgid foo@1.0.0
   

3. 从 crates.io 获取 foo 的包标识符：

   cargo pkgid https://github.com/rust-lang/crates.io-index#foo
   

4. 从本地包获取 foo 的包标识符：

   cargo pkgid file:///path/to/local/package#foo
   

SEE ALSO

cargo(1)、cargo-generate-lockfile(1)、cargo-metadata(1)、 Package ID Specifications、JSON messages