08-cargo tree

cargo-tree(1) 显示依赖树

7 分钟阅读

译文 · 基于 The Cargo Book

cargo-tree(1)

原文链接: https://doc.rust-lang.org/cargo/commands/cargo-tree.html

名称

cargo-tree — 以树形可视化显示依赖图

大纲

cargo tree [options]

描述

此命令会在终端显示依赖树。以下是一个依赖 “rand” 包的简单项目示例：

myproject v0.1.0 (/myproject)
└── rand v0.7.3
    ├── getrandom v0.1.14
    │   ├── cfg-if v0.1.10
    │   └── libc v0.2.68
    ├── libc v0.2.68 (*)
    ├── rand_chacha v0.2.2
    │   ├── ppv-lite86 v0.2.6
    │   └── rand_core v0.5.1
    │       └── getrandom v0.1.14 (*)
    └── rand_core v0.5.1 (*)
[build-dependencies]
└── cc v1.0.50

标记为 (*) 的包已被“去重”。该包的依赖已在图中其他位置显示，因此不会重复。使用 --no-dedupe 选项可重复显示重复项。

-e 标志可用于选择要显示的依赖种类。“features” 种类会改变输出，显示每个依赖启用的特性。例如 cargo tree -e features：

myproject v0.1.0 (/myproject)
└── log feature "serde"
    └── log v0.4.8
        ├── serde v1.0.106
        └── cfg-if feature "default"
            └── cfg-if v0.1.10

在此树中，myproject 依赖启用了 serde 特性的 log。log 又依赖启用了 “default” 特性的 cfg-if。使用 -e features 时，配合 -i 标志查看特性如何流入某个包会很有帮助。更多细节见下方示例。

特性统一

此命令显示的图更接近 Cargo 实际构建时经过特性统一后的图，而非你在 Cargo.toml 中列出的内容。例如，若你在 [dependencies] 与 [dev-dependencies] 中都指定了同一依赖但启用了不同特性，此命令可能会合并所有特性，并在其中一个依赖上显示 (*) 表示重复。

因此，若要大致等价地了解 cargo build 的行为，cargo tree -e normal,build 相当接近；若要大致等价地了解 cargo test 的行为，cargo tree 相当接近。然而，它并不保证与 Cargo 实际构建完全一致，因为编译很复杂并取决于许多不同因素。

要了解更多关于特性统一的内容，请参阅专门章节。

选项

树选项

-i spec

--invert spec

显示给定包的反向依赖。此标志会反转树，显示依赖该包的包。

请注意，在工作空间中，默认仅显示当前目录下工作空间成员树内该包的反向依赖。可用 --workspace 标志扩展为显示整个工作空间内该包的反向依赖。可用 -p 标志仅显示给定 -p 包子树内该包的反向依赖。

--prune spec

从依赖树显示中剪枝掉给定包。

--depth depth

依赖树的最大显示深度。例如深度 1 只显示直接依赖。

若给定值为 workspace，则仅显示当前工作空间的成员依赖。

--no-dedupe

不对重复依赖去重。通常，当某个包已显示过其依赖后，后续出现不会再重复显示其依赖，并会包含 (*) 表示已显示过。此标志会导致重复项再次显示。

-d

--duplicates

仅显示存在多个版本的依赖（隐含 --invert）。与 -p 标志一起使用时，仅显示给定包子树内的重复项。

避免多次构建同一包对构建时间和可执行文件大小都有好处。此标志可帮助识别问题包。随后你可以调查依赖较旧版本的包是否可以更新到较新版本，以便只构建一个实例。

-e kinds

--edges kinds

要显示的依赖种类。接受逗号分隔的值列表：

all — 显示所有边种类。
normal — 显示普通依赖。
build — 显示构建依赖。
dev — 显示开发依赖。
features — 显示每个依赖启用的特性。若这是唯一给出的种类，则自动包含其他依赖种类。
no-normal — 不包含普通依赖。
no-build — 不包含构建依赖。
no-dev — 不包含开发依赖。
no-proc-macro — 不包含过程宏依赖。

normal、build、dev 与 all 依赖种类不能与 no-normal、no-build 或 no-dev 依赖种类混用。

默认为 normal,build,dev。

--target triple

过滤匹配给定目标三元组的依赖。默认为宿主平台。使用值 all 可包含所有目标。

树格式化选项

--charset charset

选择用于树的字符集。有效值为 “utf8” 或 “ascii”。未指定时 cargo 会自动选择。

-f format

--format format

设置每个包的格式字符串。默认为 “{p}”。

这是用于显示每个包的任意字符串。以下字符串会被替换为对应值：

{p}、{package} — 包名。
{l}、{license} — 包许可证。
{r}、{repository} — 包仓库 URL。
{f}、{features} — 已启用包特性的逗号分隔列表。
{lib} — 在 use 语句中使用的包库名称。

--prefix prefix

设置每行的显示方式。prefix 值可以是以下之一：

indent（默认）— 以树形缩进显示每行。
depth — 以列表形式显示，每项前打印数字深度。
none — 以扁平列表显示。

包选择

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

工作空间的默认成员可在根清单中通过 workspace.default-members 键显式设置。若未设置，虚拟工作空间将包含所有工作空间成员（等价于传入 --workspace），非虚拟工作空间则仅包含根 crate 本身。

-p spec…
--package spec…: 仅显示指定的包。SPEC 格式见 cargo-pkgid(1)。此标志可指定多次，并支持常见的 Unix glob 模式，如 *、? 和 []。不过，为避免 shell 在 Cargo 处理之前意外展开 glob 模式，必须用单引号或双引号括住每个模式。
--workspace: 显示工作空间中的所有成员。
--exclude SPEC…: 排除指定的包。必须与 --workspace 标志一起使用。此标志可指定多次，并支持常见的 Unix glob 模式，如 *、? 和 []。不过，为避免 shell 在 Cargo 处理之前意外展开 glob 模式，必须用单引号或双引号括住每个模式。

清单选项

--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。

特性选择

特性标志用于控制启用哪些特性。若未指定特性选项，每个所选包都会激活 default 特性。

参见特性文档了解更多详情。

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

显示选项

-v

--verbose

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

-q

--quiet

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

--color when

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

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

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

通用选项

+toolchain

若 Cargo 通过 rustup 安装，且传给 cargo 的第一个参数以 + 开头，则会被解释为 rustup 工具链名称（例如 +stable 或 +nightly）。关于工具链覆盖如何工作，见 rustup 文档。

--config KEY=VALUE or 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 查看详情。

环境

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

退出状态

0：Cargo 成功。
101：Cargo 未能完成。

示例

显示当前目录中包的树：
```
cargo tree
```
显示所有依赖 syn 包的包：
```
cargo tree -i syn
```
显示每个包上启用的特性：
```
cargo tree --format "{p} {f}"
```
显示所有被多次构建的包。若树中出现多个 SemVer 不兼容版本（如 1.0.0 与 2.0.0），就可能发生这种情况。
```
cargo tree -d
```

解释 syn 包为何启用了某些特性：

cargo tree -e features -i syn

-e features 标志用于显示特性。-i 标志用于反转图，显示依赖 syn 的包。可能的输出示例：

syn v1.0.17
├── syn feature "clone-impls"
│   └── syn feature "default"
│       └── rustversion v1.0.2
│           └── rustversion feature "default"
│               └── myproject v0.1.0 (/myproject)
│                   └── myproject feature "default" (command-line)
├── syn feature "default" (*)
├── syn feature "derive"
│   └── syn feature "default" (*)
├── syn feature "full"
│   └── rustversion v1.0.2 (*)
├── syn feature "parsing"
│   └── syn feature "default" (*)
├── syn feature "printing"
│   └── syn feature "default" (*)
├── syn feature "proc-macro"
│   └── syn feature "default" (*)
└── syn feature "quote"
    ├── syn feature "printing" (*)
    └── syn feature "proc-macro" (*)

阅读此图时，你可以从根节点沿每条特性的链追溯其被包含的原因。例如，“full” 特性由 rustversion crate 添加，它来自 myproject（启用了默认特性），而 myproject 是命令行选中的包。所有其他 syn 特性都由 “default” 特性添加（“quote” 由 “printing” 和 “proc-macro” 添加，二者都是默认特性）。

若难以对照去重后的 (*) 条目，可尝试使用 --no-dedupe 标志获取完整输出。

参见

cargo(1), cargo-metadata(1)

最后修改 August 11, 2026: 更新 (70a5af133)