Cargo clean 完全指南:从 target 目录清理到全局缓存回收的实战手册

原创2026-09-21 19:47:112,205 阅读
文章标签:开发工具构建工具包管理器CLI

Cargo clean 完全指南:从 target 目录清理到全局缓存回收的实战手册

本文以 Cargo 官方手册 cargo-clean(1) 为骨架,结合本仓库(The Rust package manager)中 cargo clean 的 CLI 定义、核心实现与测试用例,系统讲解 Cargo 如何清理构建产物。读完本文,你将掌握 cargo clean 的全部选项语义、定向清理的底层原理、--dry-run 的安全演练技巧,以及 -Zgc 实验性子命令下的全局缓存回收能力。

命令概览:NAME 与 SYNOPSIS

cargo clean 的功能一句话可以概括为:移除 Cargo 在过去构建过程中于 target 目录里生成的产物(artifacts)。

cargo clean [options]

它的典型调用形式非常简单——不带任何选项时,cargo clean 会删除整个 target 目录。这正是它在日常开发中最常见的用途:当磁盘空间紧张、怀疑增量编译缓存损坏、或想从零开始一次干净的构建时,执行一条命令即可把整个构建缓存连根拔起。

工作原理:cargo clean 到底删了什么

要理解 cargo clean 的行为,首先要理解 Cargo 的构建缓存布局。Cargo 将构建产物统一放在 workspace 根目录下的 target 目录中(可通过 --target-dir、CARGO_TARGET_DIR 环境变量或 build.target-dir 配置修改),其内部按 profile 划分出 debug、release 等子目录,并包含 doc(文档)、incremental(增量编译)、build(构建脚本输出)等子目录。关于该目录结构的完整说明可参阅 build-cache.md。

从源码看,cargo clean 的整个流程集中在 cargo_clean.rs 的 clean() 函数中,其决策逻辑大致如下:

  1. 安全前置校验:如果 target 目录已存在但不是目录(且不是符号链接),Cargo 会拒绝清理并提示 "cleaning has been aborted to prevent accidental deletion of unrelated files",避免误删同名文件(cargo_clean.rs)。
  2. --doc 模式:只定位并删除各目标架构下的 doc 目录。
  3. profile 定向:若指定了 --profile 或 --release,先解析 profile 得到其目录名(profiles.get_dir_name()),再把清理范围收窄到对应子目录(cargo_clean.rs)。
  4. 兜底逻辑:如果未指定任何 package,直接整目录删除 target 与 build 目录;否则进入 clean_specs() 做“按包定向清理”(cargo_clean.rs)。

值得一提的是,Cargo 对清理完成后的反馈也很讲究:CleanContext::display_summary() 会输出形如 Removed 123 files, 45.2 MiB total 的统计信息,文件数与字节数在清理过程中实时累加(cargo_clean.rs)。

包选择(Package Selection)

当不指定任何包时,workspace 中所有包及其全部依赖的产物都会被清理。如果你只想清理部分包,Cargo 提供了两个选项:

选项 说明
-p spec...、--package spec... 只清理指定包的产物;该标志可多次指定。spec 的格式见 cargo-pkgid(1)
--workspace 清理所有 workspace 成员(members)的产物

关于 -p 的 spec 解析,源码中有几个值得注意的细节(cargo_clean.rs):

  • spec 中的版本限定符会被忽略,并输出警告 "version qualifier in -p ... is ignored",即会清理该名称下找到的所有版本;
  • spec 中的 url 限定符同样会被忽略,并给出对应警告;
  • 如果 spec 没有匹配到任何包,Cargo 会通过 edit_distance 给出“你是不是想找某某包”的拼写建议后报错退出。

而 --workspace 的实现非常直白:在 CLI 入口处把 ws.members() 中所有成员的名字直接展开进 spec 列表(src/bin/cargo/commands/clean.rs)。

清理选项(Clean Options)

--dry-run:先演练,再删除

--dry-run

该选项只显示“将要删除什么”的摘要,而不会真正删除任何文件。输出会以 Summary 开头(而非 Removed),并且末尾附带警告 no files deleted due to --dry-run。配合 --verbose(-v)使用时,会逐行列出实际会被删除的文件路径。

在 clean_dry_run 测试 中可以看到完整的行为验证:先执行 cargo clean --dry-run 得到 [SUMMARY] 0 files,构建后再执行一次,输出 [SUMMARY] N files, ... total,随后比对清理前后的目录列表,断言一个文件都没有被删除;-v 模式下则把所有待删路径打印到 stdout。

--doc:只清理文档目录

--doc

仅删除 target 目录下的 doc 子目录(由 cargo doc 生成),其余产物原样保留。在实现上,Cargo 会为每个请求的目标架构定位 target/<arch>/doc(主机架构则直接是 target/doc)并逐一删除(cargo_clean.rs)。

两点注意:

  • --doc 不能与 -p 组合使用:源码中直接 bail!("--doc cannot be used with -p"),因为按包粒度删除 doc 内容目前尚未实现(对应 issue #8790 的 FIXME 注释);
  • 指定 --target 时,--doc 会清理对应目标架构下的 doc 目录。测试 clean_doc_target 验证了这一点:cargo doc --target <triple> 后再 cargo clean --doc --target <triple>,只有 target/<triple>/doc 被删除。

--release 与 --profile:按 profile 定向清理

--release
--profile name
  • --release:只清理 release 目录下的产物;
  • --profile name:只清理名为 name 的 profile 所对应的目录。

两者的关系在 CLI 层被统一处理:profile_specified 标记为 args.contains_id("profile") || args.flag("release"),随后通过 Profiles::new 解析出该 profile 的目录名(例如 release、dev、bench、test 或自定义 profile 名称),再把 target/build 目录收窄到该子目录(cargo_clean.rs)。

clean_release 测试 展示了精确行为:cargo clean --release 之后,debug 目录依然存在,而 release 目录被整体删除。

--target-dir:指定构建产物目录

--target-dir directory

所有生成产物与中间文件的存放目录。除了该命令行选项,还可以通过 CARGO_TARGET_DIR 环境变量或 build.target-dir config 配置 指定;默认值是 workspace 根目录下的 target(见 options-target-dir.md)。

这里有一个重要的安全机制:当 --target-dir 被显式传入时,Cargo 会校验该目录是否带有合法的 CACHEDIR.TAG 标记文件。CACHEDIR.TAG 是缓存目录的行业约定标记(签名 Signature: 8a477f597d28d172789f06886806bc55),Cargo 借此确认目标目录确实是缓存目录,从而防止误删用户指定的普通业务目录。校验要求该文件必须是常规文件(不能是符号链接)、必须存在、且内容签名匹配,否则直接报错并中止清理(cargo_clean.rs)。

--target:按目标架构清理

--target tuple

只清理指定目标架构(target triple)的产物,可多次指定;默认是主机架构。tuple 的一般格式为 <arch><sub>-<vendor>-<sys>-<abi>。取值可以是:

  • rustc --print target-list 列出的任意受支持目标;
  • 特殊值 host-tuple,会被内部替换为主机目标,这在多人共享的 xtask 类项目中尤为实用(无需写死各自的主机);
  • 自定义目标规范文件(custom target specification)的路径。

该选项同样可通过 build.target config 值配置。需要注意:指定该标志后 Cargo 会进入“多目标”模式,产物被放置到按目标分隔的独立目录中,详见 build-cache.md。

显示选项(Display Options)

选项 说明
-v、--verbose 详细输出;重复两次得到 "very verbose",额外包含依赖警告与构建脚本输出。亦可通过 term.verbose 配置
-q、--quiet 不打印 Cargo 日志消息。亦可通过 term.quiet 配置
--color when 控制彩色输出:auto(默认,自动检测终端是否支持颜色)、always(始终显示颜色)、never(从不显示颜色)。亦可通过 term.color 配置

其中 -v 对 cargo clean 有独特价值:不仅 --dry-run -v 能列出待删文件清单,非 dry-run 模式下也会以 Removing 状态逐条显示正在删除的路径(见 cargo_clean.rs)。

Manifest 选项与通用选项

Manifest 选项

选项 说明
--manifest-path path 指定 Cargo.toml 的路径;默认在当前目录或其任意父目录中查找
--locked 断言使用与现有 Cargo.lock 完全一致的依赖与版本;若 lock 文件缺失、或 Cargo 因依赖解析不同而试图修改 lock 文件,则报错退出。适合 CI 等需要确定性构建的场景
--offline 阻止 Cargo 以任何理由访问网络;配合 cargo fetch 可在离线环境工作。亦可通过 net.offline 配置
--frozen 等价于同时指定 --locked 与 --offline

通用选项

选项 说明
+toolchain 通过 rustup 安装的 Cargo 会把首个以 + 开头的参数解释为工具链名(如 +stable、+nightly)
--config KEY=VALUE 或 PATH 覆盖某个 Cargo 配置值;参数为 TOML 语法 KEY=VALUE,或指向额外配置文件的路径;可多次指定
-C PATH 在执行任何操作前切换工作目录,影响默认 manifest 查找位置与 .cargo/config.toml 的发现路径;必须位于命令名之前,如 cargo -C path/to/project build。该选项仅在 nightly 通道可用,需要 -Z unstable-options
-h、--help 打印帮助信息
-Z flag 传给 Cargo 的不稳定(仅 nightly)标志,运行 cargo -Z help 查看详情

环境变量与退出状态

Cargo 会读取的完整环境变量清单参见 environment-variables.md;与 cargo clean 直接相关的是 CARGO_TARGET_DIR(指定产物目录)。退出状态码约定如下:

状态码 含义
0 Cargo 执行成功
101 Cargo 执行失败

实现细节:精确到文件级别的定向清理

当使用 -p 指定包时,Cargo 并没有“图省事”整目录删除,而是进入 clean_specs(),根据包的目标、profile 目录名与编译模式,逐个文件地精确匹配并删除。这套逻辑会清理:

  • 指纹(fingerprint)文件:按 包名- 前缀匹配 legacy fingerprint 目录中的条目;
  • 构建产物:通过 rustc_outputs() 得到每种编译模式(Build / Test / Check)下实际产出的文件类型,按前缀+后缀或精确文件名匹配,例如 rlib、rmeta、可执行文件及其 MSVC 无哈希变体;
  • uplift 拷贝:即被提升到 dest 顶层目录的最终产物(examples 会被清理到 examples 子目录;tests/bench 从不 uplift);
  • dep-info 文件:Cargo 生成的 *.d 依赖信息文件,以及 -Ztrim-paths 产生的 unremap 后缀文件;
  • 增量编译目录:incremental 下以 包名- 开头的条目;
  • split-debuginfo 文件:以 包名. 开头且后缀为 .o、.dwo、.dwp 的调试信息文件。

为保证定向清理不漏删,实现上用 DirectoriesToClean 结构先扫描目录条目、记录待删集合,最后统一执行 rm_rf(cargo_clean.rs)。此外还有两个工程细节:

  • 删除是容错的:路径不存在或不可访问时不会报错,只是跳过;
  • 字节统计会做硬链接去重:通过 FileId(unix 下为 (dev, ino),windows 下为卷序列号+文件索引)识别同一文件的多条硬链接,统计总字节数时只计一次(cargo_clean.rs)。测试 clean_accounts_for_hardlinks 专门验证了这一点。

进阶:cargo clean gc —— 全局缓存回收(实验性)

除了清理本地 target 目录,cargo clean 还内置了一个隐藏的 gc 子命令,用于清理 Cargo 的全局缓存(源码缓存、.crate 文件缓存、registry 索引、git 依赖检出与克隆)。目前它仍处于实验阶段,需要在 nightly 通道使用 -Zgc 启用(src/bin/cargo/commands/clean.rs),详细说明见 unstable.md 的 "Manual garbage collection with cargo clean" 一节。

cargo clean gc -Zgc
cargo clean gc -Zgc --max-download-age=1week
cargo clean gc -Zgc --max-git-size=0 --max-download-size=100MB

可按“年龄”或“体积”两种维度驱动回收:

  • 按年龄:--max-src-age(源码缓存)、--max-crate-age(crate 缓存)、--max-index-age(registry 索引,连带其 .crate 与 src 文件)、--max-git-co-age(git 检出)、--max-git-db-age(git 克隆)、--max-download-age(一切下载缓存数据);
  • 按体积:--max-src-size、--max-crate-size、--max-git-size、--max-download-size,删除最旧的缓存直到低于指定体积。

格式约定:DURATION 形如 "N seconds/minutes/days/weeks/months"(N 为整数);SIZE 形如 "N B/kB/MB/GB/kiB/MiB/GiB"(N 可为整数或小数,无后缀时视为字节数)。未指定任何选项时执行默认行为(会参考 cache.auto-clean-frequency 等自动回收配置),指定选项后则只执行所请求的回收动作。

实战示例

官方文档给出的两个基础示例是:

  1. 删除整个 target 目录:

    cargo clean
    
  2. 只删除 release 产物:

    cargo clean --release
    

结合前文,再补充几个高频实战组合:

# 演练:先看会删掉什么(配合 -v 列出具体文件)
cargo clean --dry-run -v

# 只清理某个包的产物(可用于 workspace 中的单包重构建)
cargo clean -p my-crate

# 清理 workspace 全部成员的产物
cargo clean --workspace

# 只删文档,保留其余构建缓存
cargo clean --doc

# 清理自定义 profile(如 release 的变体)对应的目录
cargo clean --profile release-with-debug

# 清理后全量重构建:先 clean 再 build
cargo clean && cargo build --release

相关命令

登录后查看全文
cargo