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

第46章 cargo rustdoc 命令详解

名称

cargo-rustdoc — 构建软件包文档，并指定自定义标志

概要

cargo rustdoc [options] [-- args]

描述

此命令会为目标（当前包，或如果提供了 -p 参数则指定该包）生成文档。指定的 args 将传递给最终的 rustdoc 调用。该命令不会为依赖项生成文档。请注意，rustdoc 仍会无条件接收 -L、--extern 和 --crate-type 等参数，而指定的 args 会被直接附加到 rustdoc 的调用命令中。

关于 rustdoc 标志的文档，请参见 https://doc.rust-lang.org/rustdoc/index.html。

当提供额外参数时，此命令要求只能编译一个目标。如果当前包有多个可用目标，必须使用 --lib、--bin 等过滤器来选择要编译的目标。

若要向 Cargo 启动的所有 rustdoc 进程传递标志，请使用 RUSTDOCFLAGS 环境变量或 build.rustdocflags 配置项。

选项

文档选项

--open: 在构建完成后在浏览器中打开文档。这将使用默认浏览器，除非在 BROWSER 环境变量中指定了其他浏览器，或使用了 doc.browser 配置项。

包选择

默认选择当前工作目录中的包。可以使用 -p 标志在工作区中选择一个不同的包。

-p spec
--package spec: 要生成文档的软件包。SPEC 的格式参见 cargo-pkgid(1)。

目标选择

若未指定目标选择选项，cargo rustdoc 将生成所选软件包中所有二进制目标和库目标的文档。如果二进制目标的名称与库目标相同，该二进制目标将被跳过。如果 required-features 缺失，对应的二进制目标也会被跳过。

传入目标选择标志后，将仅生成指定目标的文档。

注意，--bin、--example、--test 和 --bench 标志也支持常见的 Unix glob 模式，如 *、? 和 []。然而，为避免 Shell 在 Cargo 处理之前意外展开 glob 模式，必须使用单引号或双引号包裹每个 glob 模式。

--lib: 生成软件包中库的文档。
--bin name…: 生成指定二进制的文档。此标志可多次指定，并支持常见的 Unix glob 模式。
--bins: 生成所有二进制目标的文档。
--example name…: 生成指定示例的文档。此标志可多次指定，并支持常见的 Unix glob 模式。
--examples: 为所有示例目标生成文档。
--test name…: 为指定的集成测试生成文档。该选项可以多次指定，并支持常见的 Unix glob 模式。
--tests: 为所有设置了 test = true manifest 标志的目标生成文档。默认包括作为 unittest 构建的库和二进制文件，以及集成测试。注意这也会构建所需的依赖，因此 lib 目标可能被构建两次（一次作为 unittest，一次作为二进制文件、集成测试等的依赖）。可以在 manifest 中对目标设置 test 标志来启用或禁用目标。
--bench name…: 为指定的 benchmark 生成文档。该选项可以多次指定，并支持常见的 Unix glob 模式。
--benches: 为所有设置了 bench = true manifest 标志的目标生成文档。默认包括作为 benchmark 构建的库和二进制文件，以及 bench 目标。注意这也会构建所需的依赖，因此 lib 目标可能被构建两次（一次作为 benchmark，一次作为二进制文件、benchmark 等的依赖）。可以在 manifest 中对目标设置 bench 标志来启用或禁用目标。
--all-targets: 为所有目标生成文档。等同于指定 --lib --bins --tests --benches --examples。

特性选择

特性标志可用于控制启用哪些特性。如果未指定任何特性选项，将为所有选中的包激活 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 specification 的路径。详见 Custom Target Lookup Path。

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

注意，指定此标志后，Cargo 会以不同模式运行，target 产物将存放在独立目录中。详见 build cache 文档。

-r

--release

使用 release profile 为优化后的产物生成文档。也可使用 --profile 选项按名称指定特定 profile。

--profile name

使用指定的 profile 生成文档。有关 profile 的更多细节，参见参考文档。

--timings

输出每次编译耗时及随时间变化的并发信息。

构建结束后，会在 target/cargo-timings 目录下生成 cargo-timing.html 文件。若需查看历史运行记录，文件名中会附加时间戳。这些报告仅供人工阅读，不提供机器可读的 timing 数据。

输出选项

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

显示选项

-v

--verbose

输出详细信息。指定两次可获得「非常详细」的输出，其中包含额外信息，如依赖警告和 build script 输出。也可以通过 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。

通用选项

+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，且其中之一构建失败，使用 cargo rustdoc -j1 时，成功的那个 crate 可能构建也可能不构建（取决于 Cargo 先运行哪一个）；而使用 cargo rustdoc -j1 --keep-going 时，即使先运行的那个失败，两个构建也一定会都执行。

--output-format