Cargo 1.94 开发周期全解析

本文基于 Rust 官方 Inside Rust 博客 2026 年 2 月 18 日发布的《This Development-cycle in Cargo: 1.94》，由 Cargo 团队成员 Ed Page 执笔，涵盖过去约 6 周的 Cargo 开发进展。

内容结构概览

本期插件推荐：cargo-edit
实现进展
- 构建目录布局（Build dir layout）
- Target 目录加锁（Target dir locking）
- 结构化日志（Structured logging）
- TOML 1.1 支持
- cargo-cargofmt：Cargo.toml 格式化工具
- lockfile-path 配置字段化
设计讨论：Workspace 与配置发现
杂项改进
暂无进展的关注领域
如何参与贡献

一、本期插件推荐：cargo-edit

每个开发周期，Cargo 团队都会推荐一个社区插件。本期推荐的是 cargo-edit，它提供了一组用于编辑 Cargo.toml 文件的命令。

值得一提的是，cargo add 和 cargo rm 两个子命令已经被合并进 Cargo 官方工具链本身。而 cargo-edit 目前额外提供的功能包括：

cargo upgrade ：用于修改依赖的版本要求（对应 Cargo 官方 issue #12425，尚在跟踪中）。
cargo set-version ：用于修改 package.version 字段（目前尚无合并进官方 Cargo 的计划）。

本次推荐来自社区用户 kpreid 的建议。如果你也有想推荐的插件，欢迎在 Zulip 的 t-cargo 频道提交建议。

二、实现进展

2.1 构建目录布局（Build dir layout）

本节为 Cargo 1.93 相关工作的后续更新。

ranger-ross 提交了 #16502，更新了 Cargo 内部关于构建目录布局的文档。这份文档为代码审查提供了新的视角，从而引发了一系列进一步的细化改进，包括 #16514、#16515 和 #16519。

在另一个独立的修改中，epage 此前曾提议让 CARGO_BIN_EXE_* 在运行时也可用（而不仅限于编译时），但在发现该特性并非必需后选择了放弃。后来，在分析了第一次 crater 运行的结果之后，他决定重新推进这一特性，目的是减少此次变更对整个 Rust 生态的影响，同时也可能带来其他收益，相关工作记录在 #16421。

此外，epage 还尝试在新的构建目录布局上运行 Cargo 的完整测试套件（#16375），并由此引出了 #16348。目前，新一轮 crater 测试已经启动，结果分析正在进行中。

2.2 Target 目录加锁（Target dir locking）

本节同样为 Cargo 1.93 相关工作的后续更新。

在上一次更新之后，团队又发现了新的挑战：在读取指纹（fingerprint）以决定是否需要修改缓存条目时，必须持有锁。而锁的升级与降级（lock upgrading/downgrading）存在死锁风险。

上一次更新中，团队提出了"由顶层构建操作持有所有锁，并以独占方式获取"的方案，这有助于解决指纹问题------在读取指纹之前先获取锁，即可保证数据一致性。但这也意味着，两个相同的构建操作会相互竞争锁。不过，来自 rust-analyzer 的 cargo check 与 cargo test（内部包含 cargo build）或 cargo clippy 之间通常不会产生竞争。

然而，有几种容易被忽视但相当重要的场景仍然存在竞争：

对于 cargo check 与 cargo clippy：cargo clippy 只为 workspace 成员生成独立的缓存条目，因此非 workspace 成员之间会竞争锁。
对于 cargo check 与 cargo test：虽然缓存条目通常是独立的（参见 issue #3501），但 proc-macro 和 build script 是例外，它们之间会出现竞争。

团队决定暂时搁置上述问题，先合并一个最小化设计，后续再逐步迭代。以下几个问题也被一并推迟处理：

动态 rlimits（相关讨论）
为用户提供阻塞提示信息（相关讨论）
在构建线程被阻塞时复用线程处理其他构建单元，而不是让其空等

完成上述取舍后，#16155 已成功合并。后续待处理事项正在 issue #4282 中跟踪。

2.3 结构化日志（Structured logging）

本节为 Cargo 1.93 相关工作的后续更新。

weihanglo 持续推进这一方向，本周期完成了多项工作：

代码重构 （#16485）
文档补充 （#16476）
补全 cargo report timings 的缺失功能 （#16414、#16441）
新增 cargo report rebuild （#16456、#16408、#16448）：用于查看触发重新构建的原因
新增 cargo report sessions （#16428）：用于获取在 cargo report timings 和 cargo report rebuild 中使用的会话 ID
为 cargo report * 命令提供 man 页 （#16432、#16430）
移除不稳定的 --timings=FMT 选项 （#16420）：因为它与 cargo report timings 功能重复

weihanglo 还在项目目标跟踪 issue 中发布了一份总结，说明了走向稳定版本的剩余步骤，以及社区可以如何提供帮助。

2.4 TOML 1.1 支持

2025 年 12 月 18 日，TOML v1.1 规范正式发布。此版本的核心变化是：内联表（inline table）中现在允许换行 。同一天，toml crate 的 v0.9.10 版本也随之发布，提供了对 TOML 1.1 文件的解析支持。

Cargo 团队在 Zulip 上讨论了如何推进这一过渡。主要关注点在于：用户可能在不经意间使用了 TOML v1.1 的语法特性，从而将解析 manifest 所需的 Cargo 最低版本无意中提高。这也正是官方鼓励开发者在 CI 中验证 rust-version 字段的原因之一。

不过，这一影响的范围相对有限：cargo package 在发布时会重写 Cargo.toml，重写时会限定在 TOML v0.5 或更早的语法特性范围内，因此对于发布到 crates.io 的包来说风险较小。影响主要集中在通过 git patch 直接引用原始代码仓库的场景中。

此外，还有一个需要注意的细节：toml crate 目前不会区分时间字段中的秒数是被省略还是设为 0，而是假设秒数从不省略，且 0 纳秒始终被省略。如果未来 toml 开始保留这一信息，同时某个 Cargo.toml 字段（很可能仅出现在 [*.metadata] 中）使用了时间格式，并且用户以新语法书写，那么 cargo package 生成的重写后的 Cargo.toml 将需要更新版本的 Cargo 才能解析。

理论上，Cargo 可以检测 TOML v1.1 特性的使用情况，并在 package.rust-version 字段版本过低时发出警告，但团队认为这不是阻塞问题，因为这与 Cargo 中其他任何字段提升 MSRV 的情况本质上是一样的。

Cargo 对 TOML v1.1 的支持已于 2025 年 12 月 28 日通过 #16415 合并。

2.5 cargo-cargofmt：Cargo.toml 格式化工具

社区长久以来都希望 cargo fmt 在格式化 Rust 代码的同时也能格式化 Cargo.toml 文件（参见 rustfmt issue #4091）。这一需求迟迟未能推进的主要原因是：Cargo.toml 文件的官方风格指南与实际的使用习惯和社区预期之间存在明显偏差。虽然相关改进方案在 Zulip 上讨论过，但进展一度陷入停滞。

为此，epage 创建了 cargo-cargofmt 作为风格指南思路的试验床，同时探索具体的实现路径。他对历史讨论进行了系统整理，并对现有格式化工具进行了横向对比。

iepathos 随后加入，扩展了格式化规则，其中包括一项颇为复杂的工作：在单行数组与多行数组之间进行自动转换（cargo-cargofmt#37）。将内联表转为多行格式的功能被暂时推迟，因为这可能需要引入新的 Style Edition，以确保包的 MSRV 足够支持相关语法。

目前 cargo-cargofmt 支持的功能可参见 cargo-cargofmt#25，正在考虑实现的功能可参见 issues 列表。

2.6 lockfile-path：从 CLI 标志迁移到配置字段

本节为 Cargo 1.82 相关工作的后续更新。

此前，Cargo 已经以不稳定特性的形式添加了 --lockfile-path ../Cargo.lock CLI 标志（#14326）。在 issue #15510 中，有用户希望也能通过环境变量来设置这一路径。

在讨论中，团队决定将这一功能从 CLI 标志迁移到配置字段。原因在于，配置字段天然支持通过环境变量（如 CARGO_RESOLVER_LOCKFILE_PATH）和 --config 传参进行设置，功能更加完整。

此外，团队还有一个重要的考量：要尽量让用户能通过 cargo <cmd> --help 找到他们需要的功能。CLI 标志越多，用户越难找到想要的那个，反而会让人误以为 Cargo 不支持某个功能并去寻找其他变通方案。这种权衡此前在 --out-dir / --artifact-dir 的讨论中（#6100）也曾出现过。综合考虑，将此类功能"隐藏"在配置文件中是更合适的选择。

weihanglo 在 #16510 中新增了 resolver.lockfile-path 配置字段。原有的 --lockfile-path 标志将在后续开发周期中移除，以给调用方足够的时间完成迁移。

三、设计讨论：Workspace 与配置发现

如果你不小心把一个 Cargo.toml 文件复制到了 home 目录，那么在没有显式 [workspace] 表的情况下，所有包的构建都会因此失败。同样的问题适用于任何损坏的或仅在 nightly 版本上有效的 Cargo.toml 或 .cargo/config.toml 文件------只要它们出现在某个父目录中（参见 issue #6646、#6706）。这是因为 Cargo 在处理当前 manifest 时，会向上查找以判断它是否属于某个 workspace。

针对这一问题，团队从多个角度讨论了改进方向：

改进错误信息 ：至少可以优化报错提示，相关跟踪在 issue #6706。同时，也应该阻止新用户在 home 目录下不小心创建包（#16562）。

应对 nightly manifest 的情况 ：Cargo 可以先检查父目录的 Cargo.toml 是否包含 [workspace] 表，如果没有则跳过该文件，延迟 nightly 特性检查。不过，nightly 特性本身也可能影响 workspace 的发现过程，这使得问题更为复杂。

opt-in/opt-out workspace 自动发现 ：对于 manifest 文件，现有的变通方案是在包中添加一个空的 [workspace] 表。但如果在子目录中运行 cargo new，新包会被自动添加为成员，这并不总是符合预期。

团队提出了将 $`package.workspace = " "`$ (https://doc.rust-lang.org/cargo/reference/manifest.html#the-workspace-field "package.workspace = "<path>"") 扩展为支持 package.workspace = <bool> 的方案，允许用户选择是否参与 workspace 的自动发现。通过设置 package.workspace = false，可以阻止 Cargo 向上遍历目录树去查找 workspace。值得注意的是，Cargo script 目前就是以禁用 workspace 自动发现为默认行为的，而上述布尔值语法可能就是允许重新启用该行为的方式。这一想法正在 issue #16563 中跟踪。

对于 workspace 和配置发现行为的更广泛改进，团队正在 issue #7871 中综合跟踪。

四、杂项改进

osiewicz 在 #16264 中加速了 cargo clean -p 和 cargo clean --workspace 的执行速度。
作为 Cargo 1.93 自定义最终产物（custom final artifacts）功能的后续更新，ranger-ross 在 #16436 中新增了不稳定支持：构建脚本现在可以在没有 package.links manifest key 的情况下使用 cargo::metadata。

五、暂无进展的关注领域

以下是 Cargo 团队成员正在关注、但本开发周期内没有可报告进展的方向：

有待认领 owner 的项目目标：

稳定化公/私依赖（public/private dependencies）
原型化一组新的 Cargo"管道"命令（plumbing commands）
完成 libtest JSON 输出实验

已准备好开发、等待推进：

Open namespaces（开放命名空间）
自动生成命令补全（auto-generate completions），参见 clap#3166

规划中：

禁用默认特性（#3126）
RFC #3416：features metadata
- RFC #3487：visibility（可见性）
- RFC #3486：deprecation（弃用）
- 不稳定特性列表
Pre-RFC：全局互斥特性（global, mutually exclusive features）
RFC #3553：Cargo SBOM Fragment
操作系统原生配置/缓存目录支持（如 XDG）

六、如何参与贡献

如果你对 Cargo 有改进想法，官方建议先查阅 backlog，然后在 Internals 论坛进行讨论。

如果有你特别希望推进的 issue，可以通过以下方式帮助推动进展：

整理现有讨论 ：将分散的讨论汇总为清晰的综述，帮助后来者快速了解背景（可参考 Better support for docker layer caching、MSRV-aware resolver 等示例）。
整理其他生态的先例：记录其他语言生态中类似问题的解决方案，以便在设计时借鉴，同时保持对用户的熟悉感。
梳理 Cargo 内部的相关问题：分析与目标问题相关的已有设计，判断我们是否在正确的抽象层面上解决问题。
在上述基础上提出解决方案 ：综合以上信息，提出一个兼顾 Cargo 兼容性要求的方案（参考示例）。

对于状态为 S-accepted 的 issue，Cargo 团队在 Zulip 上提供 mentoring 支持，并在贡献者 Office Hours 期间可以实时交流。如果你想参与某个较大的项目，建议先从处理一些具体 issue 开始，熟悉流程和预期。如果你希望独立推进某个没有 mentor 的任务，则需要有更高的自主解决问题的能力。

原文地址：https://blog.rust-lang.org/inside-rust/2026/02/18/this-development-cycle-in-cargo-1.94/

作者：Ed Page，代表 Cargo 团队