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

第55章 cargo tree 命令详解

名称

cargo-tree — 以树状图形式展示依赖关系

概要

cargo tree [选项]

描述

该命令会在终端输出依赖树。以下是一个依赖 “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 实际构建的内容完全一致，因为编译过程很复杂，取决于许多不同的因素。

想深入了解 feature 统一（feature unification），请参阅专门章节。

选项

Tree 选项

-i spec

--invert spec

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

注意，在 workspace 中，默认只会在当前目录所在 workspace 成员的依赖树内显示该包的反向依赖。可以使用 --workspace 标志将其扩展到整个 workspace 范围。使用 -p 标志则只在 -p 指定包的子树中显示其反向依赖。

--prune spec

从依赖树的显示中剔除指定的包。

--depth depth

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

如果给定值为 workspace，则只显示属于当前 workspace 成员的依赖。

--no-dedupe

不对重复依赖项进行去重。通常情况下，如果某个包的依赖项已显示过，后续再次出现时不会重新列出其依赖项，而是用 (*) 表示已展示过。使用此标志后，这些重复项会被完整重复显示。

-d

--duplicates

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

避免同一包被多次编译有助于缩短构建时间、减小可执行文件体积。此标志有助于定位造成重复的包。随后可以检查依赖旧版本重复项的包是否可更新到新版本，从而确保只编译一份实例。

-e kinds

--edges kinds

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

all — 显示所有类型的依赖。
normal — 显示常规依赖。
build — 显示构建依赖。
dev — 显示开发依赖。
features — 显示每个依赖启用的 feature。若仅此类型被指定，会自动包含其他依赖类型。
no-normal — 不包含常规依赖。
no-build — 不包含构建依赖。
no-dev — 不包含开发依赖。
no-proc-macro — 不包含过程宏依赖。

normal、build、dev 和 all 依赖类型不能与 no-normal、no-build 或 no-dev 依赖类型混合使用。

默认值为 normal,build,dev。

--target triple

过滤匹配指定 target triple 的依赖。默认值是宿主平台。使用值 all 可包含所有目标平台。

树格式化选项

--charset charset

选择树的字符集。有效值为“utf8”或 “ascii”。若未指定，cargo 会自动选择合适的值。

-f format

--format format

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

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

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

--prefix prefix

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

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

包选择

默认情况下，如果没有指定包选择选项，所选的包取决于当前使用的清单文件（未指定 --manifest-path 时以当前工作目录为准）。如果清单是某个 workspace 的根，则选中该 workspace 的默认成员，否则只选中清单中定义的那个包。

workspace 的默认成员可以通过根清单中的 workspace.default-members 键显式设置。如果未设置，虚拟 workspace 会包含所有成员（等同于传入 --workspace），非虚拟 workspace 则只包含根 crate 本身。

-p spec…

--package spec…

只显示指定的包。SPEC 格式参见 cargo-pkgid(1)。此标志可以指定多次，并支持 *、?、[] 等常见的 Unix glob 模式。不过，为避免 shell 在 Cargo 处理之前就把 glob 模式展开，每个模式必须用单引号或双引号包裹。

--workspace

显示 workspace 中的所有成员。

Cargo tree 常用选项： - `--exclude SPEC`（可多次指定）：排除指定包。此选项必须与 `--workspace` 配合使用。支持 Unix 通配符，如 `*`、`?` 和 `[]`。注意：为避免 shell 在 Cargo 处理前就展开这些通配符，请始终将每个模式用单引号或双引号包裹。清单选项： - `--manifest-path path`：指定 `Cargo.toml` 文件的路径。默认情况下，Cargo 会在当前目录或其父目录中查找 `Cargo.toml`。 - `--locked`：断言当前使用的依赖项及版本与生成现有 `Cargo.lock` 文件时完全一致。若出现以下任一情况，Cargo 将报错退出：① 缺少 lock 文件；② 因依赖解析方式不同而试图修改 lock 文件。该选项适用于需要确定性构建的场景，例如 CI 流水线。 - `--offline`：禁止 Cargo 访问网络。若不设置此选项，Cargo 在需要联网但网络不可用时将报错；设置后，Cargo 会尽可能在离线状态下继续执行。注意：离线模式的依赖解析结果可能与在线模式不同。Cargo 仅使用本地已下载的 crate，即使本地索引显示存在更新版本。可在切换为离线模式前，使用 `cargo fetch` 预先下载依赖。

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

--frozen

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

Feature 选择

Feature 标志用于控制哪些 Feature 被启用。若未提供任何 Feature 选项，将为每个选定的包激活 default Feature。

更多细节请参阅Feature 文档。

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

显示选项

-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 或 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 查看详情。

环境变量

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

退出状态码

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

示例

显示当前目录中包的依赖树：
```
cargo tree
```
显示依赖 syn 包的所有包：
```
cargo tree -i syn
```
显示每个包启用的特性（features）：
```
cargo tree --format "{p} {f}"
```
显示被构建多次的包。这种情况通常是因为依赖树中出现了多个不兼容的版本（例如 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 引入，而该 crate 又被 myproject（使用默认特性）引入，myproject 则是命令行中指定的包。其他 syn 特性均由 “default” 特性引入（其中 “quote” 特性由 “printing” 和 “proc-macro” 引入，这两者本身也是默认特性）。

如果难以区分去重后的 (*) 条目，可尝试添加 --no-dedupe 标志以获取完整输出。