第37章 Cargo clean 命令详解

名称

cargo clean —— 移除构建产物

用法

cargo clean [选项]

描述

移除 target 目录中 Cargo 历史生成的产物。

若未指定选项，cargo clean 将删除整个 target 目录。

选项

包选择

未指定包时，将清理工作区内的所有包及其依赖。

-p spec…

--package spec…

仅清理指定的包，可多次使用此选项。关于 SPEC 格式，请参阅 cargo-pkgid(1)。

--workspace

清理工作区成员的产物。

清理选项

--dry-run

仅显示将被删除的内容摘要，不实际删除。配合 --verbose 使用可列出具体将被删除的文件。

--doc

此选项使 cargo clean 仅移除 target 目录下的 doc 目录。

--release

移除 release 目录中的所有产物。

--profile name

删除指定 profile 目录下的所有构建产物。

--target-dir directory

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

--target triple

清理指定目标架构的产物。该标志可多次指定，默认使用宿主机架构。三元组的通用格式为 <arch><sub>-<vendor>-<sys>-<abi>。

可能的取值：

• rustc --print target-list 中列出的任意受支持的目标。
• "host-tuple"，内部会被替换为宿主机的目标三元组。这在交叉编译某些 crate 时特别有用，当你不希望将宿主机架构作为目标时（例如，在一个由多台机器共同开发的共享项目中，xtask 需要适配多种宿主机）。
• 自定义目标规范文件的路径。更多信息参见 自定义目标查找路径。

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

注意，指定该标志会使 Cargo 进入不同运行模式，目标产物会被放置在单独的目录中。更多细节参见 构建缓存文档。

显示选项

-v

--verbose

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

-q

--quiet

不打印 cargo 的日志信息。也可以通过 term.quiet config value 来设置。

--color when

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

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

也可以通过 term.color config value 来设置。

Manifest 选项

--manifest-path path

Cargo.toml 文件的路径。默认情况下，Cargo 会在当前目录及其各级父目录中查找 Cargo.toml 文件。

--locked

要求依赖及版本与现有 Cargo.lock 文件生成时完全一致。出现以下任一情况时，Cargo 将报错退出：

• lock 文件缺失。
• 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 查看详情。

环境变量

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

退出状态

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

示例

1. 删除整个 target 目录：

   cargo clean
   

2. 仅删除 release 产物：

   cargo clean --release
   

另请参阅

cargo(1), cargo-build(1)