给 target 做一次“功能分区”：Rust 官方邀测 Cargo 构建目录 v2

Cargo 的 target 目录，Rust 开发者都不陌生。

几个项目下来，磁盘占用几十个 GB 是常事。切个分支，Cargo 又可能从头编译一大片。删了重来？依赖得重新下载，中间产物得重新生成。

这种状态持续了很多年。不是没人想改，是这事牵一发而动全身。构建目录的布局，虽说是Cargo 的内部细节，但太多工具和脚本已经“依赖”了这些未指定的细节——比如从测试文件路径反推二进制文件路径，比如构建脚本里写死 OUT_DIR 的查找逻辑。

2026 年 3 月 13 日，Rust 官方博客发布了一篇“召集令”：《Call for testing: Build directory layout v2》。不是小修小补，是对 target 目录的布局做一次根本性的调整。

“胖” target 的烦恼

Rust 开发者，大概都经历过这种场景：

项目开发中，打开磁盘分析工具一看，各个 Rust 项目的 target 目录加起来几十个 GB。删了吧，下次构建得从头下载依赖、重新编译；不删吧，看着那些重复存储的依赖包，心里总不是滋味。

更让人抓狂的是分支切换。你在 main 分支上编译了一遍，切到 feature/new-feature 分支，Cargo 往往又要重新编译一大片。明明两个分支的依赖 90% 都相同，它却像失忆了一样，把大部分工作重来一遍。

这背后的核心问题在于：旧的构建目录布局将不同编译配置的产出物混合存放，难以有效共享和清理。

v2 布局：按“包名+哈希”重新组织

此次征集测试的 build directory layout v2，并非推倒重来，而是对 target 目录进行一次彻底的“功能分区”。

如果把旧的 target 目录比作一个堆满各种杂物的巨大仓库——调试信息、优化后的二进制、依赖的中间文件全混在一起——那么 v2 布局就像给这个仓库装上了整齐的货架和标签系统。

核心变化在于：从“按内容类型组织”改为“按包名和构建单元的哈希值组织。”

官方博客给出了新旧布局的对比。旧布局下，target/debug/ 里散落着 .fingerprint/、build/、deps/ 等子目录，各种文件按类型堆放。

而新布局中，每个“包名+哈希”对应一个自包含的目录，里面放这个构建单元的所有产出——缓存跟踪信息、编译产物、构建脚本输出等。

这种组织方式的好处是显而易见的：

• 相同配置的构建产物只存一份。在同一个构建目录（build-dir）内，如果两个构建单元（比如不同包，或同一包的不同编译配置）的哈希值完全相同，它们会共用同一个物理目录。Cargo 构建时会直接使用已存在的产物，避免重复编译和重复占用磁盘空间。这为跨工作空间共享构建产物铺平了道路——如果用户显式配置多个工作空间使用同一个 build-dir，v2 布局能确保这种共享是可靠且高效的。
• 自动清理成为可能。当每个构建单元都装在“自包含的目录”里后，Cargo 未来可以识别出哪些目录已经不再被任何项目引用，然后安全删除，磁盘占用不再无限增长。
• 锁粒度更细。官方博客提到，v2 布局将解除后续工作的阻塞，例如让 cargo test 和 rust-analyzer 同时运行时不再互相阻塞。
• 路径长度问题有望缓解。Windows 上那个著名的“路径太长”错误，将来也可能通过调整布局结构来避免。

为什么是现在？为什么邀请测试？

布局变更，是构建系统的“心脏手术”。稍有不慎，就可能导致增量编译错误、链接失败，甚至影响 IDE 的代码跳转。

这也是为什么官方要发起这次“Call for testing”。v2 布局已经在 RFC 3415 中讨论通过，并在 Rust 1.78 版本之后以 Nightly 通道的 -Zbuild-dir-new-layout 标志存在。现在是时候让它在更广泛的场景中接受检验了。

官方希望测试的，正是那些“边缘情况”：

• 跨平台编译：比如在 Linux 上编译到 Windows 或 WASM 目标。
• 复杂工作空间：包含大量成员项目的工程。
• 与构建脚本的交互：依赖 OUT_DIR 输出文件的项目。
• 与各种工具的兼容性：如 cargo-edit、sccache、以及 IDE 插件。

但已知的故障模式已经列出来了，均来自社区反馈的 Issue：

• 从测试文件路径反推二进制文件路径：有些项目会通过测试可执行文件的路径去推断同名的二进制文件路径。修复方法是在支持 CARGO_BIN_EXE_* 环境变量的 Cargo 版本（1.94+）中使用该变量，或使用 env!("CARGO_BIN_EXE_*") 在编译时获取路径。对于旧版本可保留推断逻辑作为回退。
• 构建脚本查找 target-dir：部分构建脚本尝试从自身二进制路径或 OUT_DIR 反推 target 目录，这在新布局下会失效。相关 Issue #13663 中提供了替代方案。
• 从 rustc 查找用户请求的产物：有些外部工具通过解析 rustc 命令行来定位最终产物，新布局下需要更新这些工具的逻辑。见 Issue #13672。

Ed Page在博客里特别提到：这次改动的幕后功臣是 ranger-ross，他“tirelessly worked”（不知疲倦地工作）才把这事推进到可测试阶段。

如何参与测试？

如果你愿意帮助 Rust 团队验证这一变更，可以按照以下步骤操作：

• 更新 Rust：确保你的 Rust 工具链是最新的 Nightly 版本（2026-03-10 之后的版本）。

rustup update nightly

• 带上 flag 构建：在构建命令后加上 -Zbuild-dir-new-layout。

cargo +nightly test -Zbuild-dir-new-layout

如果你想单独测试“构建目录与最终产物目录分离”这个特性（这是 v2 布局的一部分），可以设置环境变量 CARGO_BUILD_BUILD_DIR=build 来验证。

CARGO_BUILD_BUILD_DIR=build cargo +nightly build -Zbuild-dir-new-layout

这会将中间构建产物（如依赖的编译结果）存放到 build/ 目录，而最终可执行文件仍留在 target/debug/。官方正在评估是否在 #16147 中将此变为默认行为。

官方博客特别提到，他们需要测试各种真实的项目，无论是小型的 CLI 工具，还是大型的 Web 应用或嵌入式项目。你的每一次构建，都可能成为让 v2 布局更加稳定的关键一步。

未来还会改什么？

v2 布局只是开始。官方明确表示，这次测试的经验将用于指导未来的布局调整，包括：

• 缩短路径长度：Windows 上那个“路径太长”的错误，很多 Rust 开发者都遇到过。未来可能会通过减少嵌套层级或使用更短的哈希表示来缓解。
• 移出 profile 和 target 目录：让更多产物可以在不同编译配置间共享（例如，同一依赖的 debug 和 release 版本如果能共享部分中间产物，将进一步提升构建速度）。

此外，有些改动这次没做，是因为锁机制的变更被这次布局变更阻塞了——典型的“先有鸡还是先有蛋”问题。

写在最后

v2 布局的落地，不会是终点。随着artifact dependencies、build-std 等特性的成熟，Rust 的构建系统会变得越来越灵活和高效。

对于普通 Rust 用户来说，这是一次几乎“无痛”的升级。我们只需要花几分钟配置一下环境，跑几个构建，然后向官方反馈结果。但正是这无数个“几分钟”，汇聚成了推动 Rust 进化的力量。

参考引用：

• Call for testing: Build directory layout v2
• Rust RFC 3415. Build directory layout v2

谢谢您的阅读，欢迎交流。如果您发现错别字，也请向我发信息。