Cargo clean 完全指南:从 target 目录清理到全局缓存回收的实战手册
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() 函数中,其决策逻辑大致如下:
- 安全前置校验:如果
target目录已存在但不是目录(且不是符号链接),Cargo 会拒绝清理并提示 "cleaning has been aborted to prevent accidental deletion of unrelated files",避免误删同名文件(cargo_clean.rs)。 --doc模式:只定位并删除各目标架构下的doc目录。- profile 定向:若指定了
--profile或--release,先解析 profile 得到其目录名(profiles.get_dir_name()),再把清理范围收窄到对应子目录(cargo_clean.rs)。 - 兜底逻辑:如果未指定任何 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 等自动回收配置),指定选项后则只执行所请求的回收动作。
实战示例
官方文档给出的两个基础示例是:
-
删除整个 target 目录:
cargo clean -
只删除 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(1):Cargo 命令总览
- cargo-build(1):执行构建、生成产物——
cargo clean清理的正是它的输出 - cargo-pkgid(1):
-p选项 spec 格式的权威说明 - cargo-doc(1):配合
cargo clean --doc理解文档产物