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

第39章 Rust 包管理工具 Cargo 文档构建指南（第39章）

名称

cargo-doc — 构建包文档

概要

cargo doc [选项]

描述

构建本地包及其所有依赖项的文档。输出结果以 rustdoc 的标准格式存放于 target/doc 目录中。

注意：文档生成具有累积性：在 target 目录中已有的文档文件会在不同次 cargo doc 调用间保留。若要删除已生成的文档，请通过 cargo-clean(1) 传入 --doc 参数。

选项

文档选项

--open: 构建完成后在浏览器中打开文档。除通过 BROWSER 环境变量指定浏览器外，默认使用系统默认浏览器，也可使用 doc.browser 配置选项。
--no-deps: 不为依赖项构建文档。
--document-private-items: 在文档中包含非公开项。当为二进制目标（binary target）生成文档时，此选项默认开启。

包选择

默认情况下，若未指定任何包选择选项，所选包取决于选定的 manifest 文件（若未指定 --manifest-path，则基于当前工作目录确定）。如果该 manifest 是工作区（workspace）的根文件，则选择工作区的默认成员；否则，仅选择该 manifest 定义的包。

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

-p spec…
--package spec…: 仅生成指定包的文档。SPEC 格式详见 cargo-pkgid(1)。该选项可多次指定，支持 *、?、[] 等常见 Unix 通配符模式。为防止 Shell 在 Cargo 处理前自动展开通配符，务必用单引号或双引号包裹每个模式。
--workspace: 生成工作区内所有成员的文档。
--all: --workspace 的已弃用别名。
--exclude SPEC…: 排除指定包。需配合 --workspace 使用。该选项可多次指定，支持 *、?、[] 等常见 Unix 通配符模式。为防止 Shell 在 Cargo 处理前自动展开通配符，务必用单引号或双引号包裹每个模式。

Target 选择

若未指定任何 Target 选择选项，cargo doc 将为选定的包生成所有 binary 和 library target 的文档。若 binary 名称与 library target 相同，则跳过该 binary；若 binary 缺少其 required-features 中指定的特性，也会跳过。

可在 manifest 配置中设置 target 的 doc = false 以改变默认行为。但一旦使用了 Target 选择选项，doc 标志将失效，系统会始终为指定 target 生成文档。

--lib: 为 package 的库生成文档。
--bin name…: 为指定的二进制目标生成文档。该参数可多次指定，并支持常见的 Unix glob 模式。
--bins: 为所有二进制目标生成文档。
--example name…: 为指定的示例生成文档。该参数可多次指定，并支持常见的 Unix glob 模式。
--examples: 为所有示例目标生成文档。

Feature 选择

通过 feature 相关参数可以控制启用哪些 feature。如果不指定任何 feature 选项，则每个选中的 package 都会激活 default feature。

详情请参阅 feature 文档。

-F features
--features features: 要启用的 feature 列表，以空格或逗号分隔。workspace 成员的 feature 可用 package-name/feature-name 语法启用。该参数可多次指定，所有指定的 feature 都会被启用。
--all-features: 启用所有选中 package 的全部可用 feature。
--no-default-features: 不启用选中包的 default 特性。

编译选项

--target triple

为指定的目标架构生成文档。该标志可多次指定，默认使用宿主架构。三元组（triple）的一般格式为 <arch><sub>-<vendor>-<sys>-<abi>。

可能的值包括：

rustc --print target-list 中支持的任何目标。
"host-tuple"，内部会替换为宿主机的目标架构。在交叉编译某些 crates 时，若不希望将当前宿主机指定为目标，此选项尤为有用（例如，共享项目中可能由多台宿主机共同维护的 xtask）。
指向自定义目标规范的路径。更多信息请参考Custom Target Lookup Path。

也可以通过 build.target 配置项进行指定。

注意，指定此标志会使 Cargo 进入不同模式，目标产物将被放置在独立目录中。更多详情请参阅构建缓存文档。

-r

--release

使用 release 配置文件生成优化后的产物文档。如需按名称选择特定配置文件，请参阅 --profile 选项。

--profile name

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

--timings

输出每个编译步骤的耗时，并跟踪随时间变化的并发信息。

构建结束时，会在 target/cargo-timings 目录写入 cargo-timing.html 文件。如果希望查看之前的运行记录，还会写入一份文件名中包含时间戳的额外报告。这些报告仅供人类阅读，不提供机器可读的计时数据。

输出选项

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

显示选项

-v

--verbose

使用详细输出模式。指定两次可产生“非常详细”的输出，包含依赖项警告和构建脚本输出等额外信息。也可通过配置值 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 不要直接输出 rustc 生成的 JSON 诊断信息，而是由 Cargo 自行渲染这些诊断。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 将仅限于使用本地已下载的 crates，即使本地索引副本显示存在更新的版本也是如此。请在切换到离线模式前，使用 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 channel 上可用，且需要通过 -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 doc -j1 可能会也可能不会构建成功的那个（取决于 Cargo 先调度了哪一个），而 cargo doc -j1 --keep-going 则一定会把两个构建都执行一遍，即使先执行的失败了。