Cargo 依赖解析(Dependency Resolution)深入指南:约束、启发式与 Resolver 版本演进

原创2026-09-21 15:22:371,344 阅读
文章标签:包管理器构建工具CLI开发工具依赖管理

Cargo 依赖解析(Dependency Resolution)深入指南:约束、启发式与 Resolver 版本演进

Cargo 的核心职责之一是根据各包声明的版本要求(version requirement)决定依赖使用哪个版本,这一过程被称为"依赖解析"(dependency resolution),由 Cargo 内置的 "resolver" 执行,解析结果被写入 Cargo.lock 文件以实现可复现构建。本文以 Cargo 官方参考文档《Dependency Resolution》(即本仓库 doc/book/src/reference/resolver.md)为主线,结合本仓库 src/resolver 目录下的真实实现源码,系统讲解解析器的工作约束与启发式策略、版本选择规则、Rust 版本与发布年龄等新兴约束、feature 解析机制、Resolver 版本(1/2/3)的演进差异,以及依赖更新的实操与常见故障排查手段。读完本文,你将能解释"为什么 Cargo 选中了某个版本"、理解 Cargo.lock 的优先级逻辑,并能借助 cargo tree、cargo update 等命令排查依赖解析问题。

什么是依赖解析

每个包在 Cargo.toml 的 [dependencies] 表中声明依赖时,通常只写一个版本要求(如 bitflags = "1.0"),而不是锁定到某个具体版本。Cargo 需要在这些宽松要求的约束下,结合整个依赖图的全局情况,为每个包挑选一个具体版本。这个过程就叫做依赖解析,执行解析的组件称为 resolver。

解析的最终结果被持久化到 Cargo.lock 文件中,把每个依赖"锁"到特定版本,使其在一段时间内保持不变。Cargo.lock 与 Cargo.toml 的关系详见 doc/book/src/guide/cargo-toml-vs-cargo-lock.md。解析结果的可视化可以借助 cargo tree 命令完成,例如:

$ cargo tree
my-package v0.1.0
├── bitflags v1.2.1
└── rand v0.8.5
    └── libc v0.2.170

约束与启发式:解析器的工作方式

在很多情况下并不存在唯一的"最佳"解析方案。解析器在多种**约束(constraints)与启发式(heuristics)**的共同作用下,找出一个普遍适用的解析结果。原文档给出了一段近似解析器行为的 Rust 伪代码,理解它有助于把握整个机制的脉络:

pub fn resolve(workspace: &[Package], policy: Policy) -> Option<ResolveGraph> {
    let dep_queue = Queue::new(workspace);
    let resolved = ResolveGraph::new();
    resolve_next(dep_queue, resolved, policy)
}

fn resolve_next(dep_queue: Queue, resolved: ResolveGraph, policy: Policy) -> Option<ResolveGraph> {
    let Some(dep_spec) = policy.pick_next_dep(&mut dep_queue) else {
        // Done
        return Some(resolved);
    };

    if let Some(resolved) = policy.try_unify_version(dep_spec, resolved.clone()) {
        return Some(resolved);
    }

    let dep_versions = dep_spec.lookup_versions()?;
    let mut dep_versions = policy.filter_versions(dep_spec, dep_versions);
    while let Some(dep_version) = policy.pick_next_version(&mut dep_versions) {
        if policy.needs_version_unification(&dep_version, &resolved) {
            continue;
        }

        let mut dep_queue = dep_queue.clone();
        dep_queue.enqueue(&dep_version.dependencies);
        let mut resolved = resolved.clone();
        resolved.register(dep_version);
        if let Some(resolved) = resolve_next(dep_queue, resolved, policy) {
            return Some(resolved);
        }
    }

    // No valid solution found, backtrack and `pick_next_version`
    None
}

伪代码中体现的三个关键步骤是:

  • 遍历依赖(pick_next_dep):遍历依赖的顺序会影响针对同一依赖的多条相关版本要求如何被统一(见下文"统一版本"),也会影响回溯(backtrack)的规模,进而影响解析器性能。
  • 统一版本(try_unify_version、needs_version_unification):Cargo 会在可行时尽量复用同一个版本,以减少构建时间,并允许公共依赖的类型在 API 之间传递。如果两个本可统一的版本因为其依赖规格(dependency specifications)发生冲突而无法统一,Cargo 会回溯而非直接选用多个版本;若找不到解则报错。此外,依赖规格或 Cargo 本身也可能判定某个版本"不可取",宁可回溯或报错也不使用它。
  • 优选版本(pick_next_version):Cargo 可能倾向选择某个特定版本,回溯时则退回到下一个候选版本。

真实实现:DFS 加回溯

伪代码在真实源码中对应 src/resolver/mod.rs 的 resolve 函数(入口)与 activate_deps_loop 函数(主循环)。模块级文档明确说明了算法性质:

Actually solving a constraint graph is an NP-hard problem. This algorithm is basically a nice heuristic to make sure we get roughly the best answer most of the time.

即"求解约束图本质上是 NP-hard 问题",该算法是一种启发式算法,在大多数情况下得到近似最优解。其基本策略是:深度优先搜索(DFS)+ 回溯(backtracking),总是先尝试激活"最新(版本号最高)的包",不行再退回上一个分支点尝试下一个候选(见 src/resolver/mod.rs 第 19-38 行的注释)。两个核心启发式规则是:

  1. 绝不激活不兼容的 crate 版本:只尝试真正满足依赖要求的 crate,绝不激活与已激活版本 SemVer 兼容的另一个版本(同一 SemVer 兼容区间只允许存在一个版本),也绝不激活 links 属性与已激活包冲突的版本。
  2. 总是优先激活版本号最高的 crate:Cargo 的默认依赖写法(如 foo = "0.1.2")是 SemVer 兼容的,因此选最高版本最有可能同时满足尽量多的依赖要求。

这两条规则在 RemainingCandidates::next 方法(src/resolver/mod.rs 第 750-805 行)中有直接对应:候选若与已激活版本 SemVer 兼容但不相等,则被过滤并记录 ConflictReason::Semver;若候选的 links 名已被其他包占用,则被过滤并记录 ConflictReason::Links。

值得注意的实现细节还有:

  • 主循环用显式栈(backtrack_stack)代替递归,以避免调用栈随依赖图规模线性增长(见 src/resolver/mod.rs 第 227-239 行注释)。
  • 每次激活失败时,冲突原因会被写入全局冲突缓存 past_conflicting_activations,后续遇到相同冲突集合时可跳过大量无效工作;还有 generalize_conflicting 函数尝试把冲突"泛化"到更早的分支点,实现类似 backjumping 的加速。
  • 候选排序与过滤由 src/resolver/version_prefs.rs 的 VersionPreferences::sort_summaries 完成。其排序优先级依次是:① 被偏好(preferred)的包;② 与工作区 Rust 版本最兼容(msrv_compat_count 越大越靠前);③ 按版本号排序(默认最高版本优先,--minimal-versions 时最低版本优先)。

版本号:默认选择最高版本

一般情况下,Cargo 倾向于选择当前可用的最高版本。

例如,解析图中某包声明:

[dependencies]
bitflags = "*"

如果生成 Cargo.lock 时 bitflags 的最大版本是 1.2.1,则该包会使用 1.2.1。可能的例外场景见下文 Rust 版本 一节。

在源码层面,"版本号排序"由 VersionPreferences::sort_summaries 中的 VersionOrdering 决定(src/resolver/version_prefs.rs 第 42-47 行):默认 MaximumVersionsFirst(最高版本优先),而在 -Z direct-minimal-versions 或 --minimal-versions 场景下使用 MinimumVersionsFirst。后者甚至会把候选列表截断为只剩一个(见 sort_summaries 末尾的 summaries.split_off(1)),这正是"最小版本解析"的实现方式。

版本要求:包的兼容性声明

包通过**版本要求(version requirement)**声明自己支持哪些版本、拒绝其余版本。例如:

[dependencies]
bitflags = "1.0"  # 含义是 `>=1.0.0,<2.0.0`

如果生成 Cargo.lock 时 bitflags 的最大版本是 1.2.1,则使用 1.2.1,因为它是兼容区间内的最大版本。即使之后发布了 2.0.0,仍会继续使用 1.2.1,因为 2.0.0 被视为不兼容。

版本要求的完整语法(默认要求、caret、tilde、通配符、比较符、多要求组合、预发布版本排除规则等)详见 doc/book/src/reference/specifying-dependencies.md 的 "Version requirement syntax" 一节。其中与解析最相关的几点:

  • 默认要求(也是 caret 要求的简化写法):"1.2.3" 等价于 ^1.2.3,即 >=1.2.3, <2.0.0。
  • 兼容性判定以"最左侧非零的 major/minor/patch 分量相同"为准,这与严格 SemVer 对 1.0.0 之前版本一律视为不兼容的规则不同:例如 0.2.3 表示 >=0.2.3, <0.3.0。
  • crates.io 不允许发布裸 * 版本要求。

SemVer 兼容性与统一版本

Cargo 假定包遵循 SemVer 规范,并依据 caret 版本要求(详见 specifying-dependencies.md 的默认要求)对 SemVer 兼容的依赖版本进行统一(unify)——即让两个包共享同一个版本的依赖。如果两个兼容版本因版本要求冲突而无法统一,Cargo 会直接报错。

可以统一的例子:下面两个包对 bitflags 的依赖会被统一,因为任何被选中的版本都彼此兼容:

# Package A
[dependencies]
bitflags = "1.0"  # 含义是 `>=1.0.0,<2.0.0`

# Package B
[dependencies]
bitflags = "1.1"  # 含义是 `>=1.1.0,<2.0.0`

会报错的例子:下面的版本要求直接冲突,无法选出单个版本同时满足两者,Cargo 报错:

# Package A
[dependencies]
log = "=0.4.11"

# Package B
[dependencies]
log = "=0.4.8"

不会统一的例子:下面两个包对 rand 的依赖区间互不重叠,只有彼此不兼容的版本可选,于是会解析出两个不同版本(例如 0.6.5 和 0.7.3)并分别构建:

# Package A
[dependencies]
rand = "0.7"  # 含义是 `>=0.7.0,<0.8.0`

# Package B
[dependencies]
rand = "0.6"  # 含义是 `>=0.6.0,<0.7.0`

一般不统一、但可能因其他启发式而统一的例子:下面两个要求虽然存在交集,但默认解析会为两者分别选择各自区间内的最高版本,因此通常也会产生两个版本;其他约束或启发式的介入可能让它们统一到某一个版本(如 0.6.5):

# Package A
[dependencies]
rand = ">=0.6,<0.8.0"

# Package B
[dependencies]
rand = "0.6"  # 含义是 `>=0.6.0,<0.7.0`

版本不兼容的危害(Version-incompatibility hazards)

当解析图中出现同一个 crate 的多个版本时,如果使用这些 crate 的库把其中的类型暴露到对外 API 中,就会出问题:即使类型名相同,Rust 编译器也会把它们视为不同类型。因此,库在发布 SemVer 不兼容版本(例如在 1.0.0 已被广泛使用后发布 2.0.0)时要格外谨慎,尤其是被广泛使用的库。

一种缓解方案是 "semver trick":库在发布破坏性版本的同时,给旧版本发布一个 point release,让旧版本 re-export 新版本的类型,从而在保持与旧版本兼容的同时完成破坏性变更。其细节详见原文档引用的外部说明(本仓库不包含该资料),核心思想是"新版本照常发布,旧版本补发一个重导出新版本类型的补丁版本"。

这类不兼容通常表现为编译期错误,但偶尔只表现为运行期异常。例如公共库 foo 同时以 1.0.0 和 2.0.0 出现在解析图中:如果某个使用 foo 1.0.0 的库创建了一个对象,而调用方代码用 foo 2.0.0 的类型去 downcast_ref,该向下转型会在运行期失败。

排查建议:

  • 使用 cargo tree -d(即 --duplicates)找出重复版本及其来源(详见 cargo-tree 命令文档)。
  • 确保你对多版本依赖的使用方式是正确且隔离的,尤其要避免不同版本的类型混用。
  • 发布热门库的 SemVer 不兼容版本前,充分考虑对整个生态的影响。

锁文件:Cargo.lock 的优先级

当 Cargo.lock 存在时,Cargo 会给予其中记录的版本最高优先级。这是为了在"可复现构建"与"跟随清单(manifest)变化"之间取得平衡。

沿用前面的例子:首次生成 Cargo.lock 时 bitflags 最大版本是 1.2.1,于是锁定 1.2.1。之后即使 bitflags 1.3.5 已经发布,解析时仍会使用 1.2.1,因为它已在 Cargo.lock 中。

随后你把清单改为:

[dependencies]
bitflags = "1.3.0"

此时 1.2.1 不再满足版本要求,Cargo.lock 中该条目被忽略,改用 1.3.5 并写入锁文件。

在源码层面,"锁定版本优先"由 VersionPreferences::prefer_package_id 实现(src/resolver/version_prefs.rs 第 51-53 行):构建 VersionPreferences 时会把 Cargo.lock 中的每个包 ID 标记为 preferred,随后 sort_summaries 在排序时把 preferred 的版本排在最前。should_prefer 方法(第 86-96 行)还会把 [patch] 指定的依赖也标记为偏好版本。

Rust 版本(MSRV)约束

为了支持以某个最低 Rust 版本(MSRV)进行开发,解析器可以把依赖版本与你所用 Rust 版本的兼容性纳入考量。这一行为由配置项 resolver.incompatible-rust-versions 控制。

在 fallback 设置下,解析器会优先选择 Rust 版本小于等于你所用 Rust 版本的依赖包。例如你用 Rust 1.85 开发如下包:

[package]
name = "my-cli"
rust-version = "1.62"

[dependencies]
clap = "4.0"  # 解析到 4.0.32

解析器会选中 4.0.32,因为它的 Rust 版本是 1.60.0:

  • 4.0.0 未被选中,因为它版本号更低,尽管它的 Rust 版本也是 1.60.0;
  • 4.5.20 未被选中,因为它不兼容 my-cli 的 Rust 版本 1.62——注意它的 Rust 版本 1.74.0 虽然兼容你的 1.85 工具链,但兼容性判断以包的 rust-version 声明为准,而不是以你的工具链版本为准。

如果某个版本要求下不存在 Rust 版本兼容的依赖版本,解析器不会报错,而是退而求其次挑选一个(可能次优的)版本。例如:

[package]
name = "my-cli"
rust-version = "1.62"

[dependencies]
clap = "4.2"  # 解析到 4.5.20

没有任何 clap 版本既满足 4.2 这个版本要求又兼容 Rust 1.62,于是解析器会选择不兼容的 4.5.20(其 Rust 版本为 1.74)。

需要注意的重要限制:解析器在为一个包选择依赖版本时,并不知道最终会有哪些工作区成员传递依赖该版本,因此无法只考虑与该依赖相关的那些 Rust 版本。当工作区成员拥有不同的 Rust 版本时,解析器依靠启发式寻找"足够好"的解。即使工作区中有些包没有声明 rust-version,这一规则同样适用。

可能选低的场景:工作区两个成员 a(rust-version = "1.62")与 b(未声明),两者都依赖 clap = "4.2"。虽然 b 本可使用更高的 4.5.20,但由于 a 的 Rust 版本是 1.62,最终会选择 4.0.32。

可能选高的场景:成员 a(rust-version = "1.62")要求 clap = "4.2",成员 b(未声明)要求 clap = "4.5"。虽然各自的要求单独看都能找到满足自身 Rust 版本的版本,但由于版本统一的需要,解析器必须选一个对两者都成立的版本,结果可能是 4.5.20。

MSRV 约束的相关背景参见 doc/book/src/reference/rust-version.md。源码侧,Rust 版本兼容性通过 VersionPreferences::rust_versions 记录工作区的 Rust 版本集合,并在 sort_summaries 中以 msrv_compat_count 对候选排序(src/resolver/version_prefs.rs 第 151-160 行);测试用例 test_single_rust_version、test_multiple_rust_versions 验证了多 Rust 版本下的排序行为。

发布年龄(Publish age)约束

解析器会把发布时间早于配置的 min-publish-age 阈值之外(即太新)的版本视为 pubtime-incompatible。当 resolver.incompatible-publish-age 设置为 deny 时,解析器会忽略这些太新的版本,除非它们已经存在于 Cargo.lock 中。设置为 allow 则关闭该检查;此时如果配合 cargo update --precise,Cargo 可以拉入指定版本及其传递依赖。

配置示例(对应 src/context/schema.rs 中的 CargoResolverConfig):

[resolver]
incompatible-publish-age = "deny"

[registry]
global-min-publish-age = "7 days"

源码实现位于 src/resolver/version_prefs.rs 的 PublishAgePolicy:

  • 配置键支持 registry.global-min-publish-age(全局)与 registries.<name>.min-publish-age(按注册表覆盖,优先级更高),取值可以是 "0"(禁用限制)或时间跨度字符串(如 "7 days")。
  • too_new 方法比较版本的发布时间与"调用时刻(invocation time)减去最小年龄阈值",发布时间晚于该时刻即为违规;deny 策略下违规版本会被过滤掉。
  • 同文件内的测试用例(如 publish_age_reports_exact_age、publish_age_per_registry_overrides_global)详细验证了阈值边界、按注册表覆盖、缺失发布时间等行为。

Features 与解析

为了生成 Cargo.lock,解析器会假设所有工作区成员的所有 features 全部开启来构建依赖图。这样能确保所有可选依赖(optional dependencies)在用户通过 --features 命令行参数增删 feature 时,都能被正确解析并与图的其余部分协调。而实际编译某个 crate 时,解析器会根据命令行选中的 features 再跑一次解析,以确定真正使用的 features。

这一点在 src/resolver/mod.rs 模块注释中有明确说明:"Resolution is currently performed twice"——第一次以全部 feature 开启的方式解析(结果存入 Cargo.lock),第二次只用命令行指定的 feature 解析。

依赖的解析会以所有被启用 feature 的并集进行。例如包 A 依赖 im 并启用了 serde 特性,包 B 依赖 im 并启用了 rayon 特性,则 im 会同时以两个 feature 构建,serde 与 rayon 都会进入解析图;反之,如果没有包以这些 feature 依赖 im,这些可选依赖会被忽略,不影响解析。

工作区多包构建(如 --workspace 或多个 -p 标志)时,所有被构建包的依赖 features 会统一。若你希望不同工作区成员避免这种统一,需要通过多次单独的 cargo 调用来构建。

解析器还会跳过缺少必需 feature的包版本。例如某包依赖 regex 的 ^1 版本并要求 perf feature,则它能选到的最早版本是 1.3.0(此前的版本没有 perf feature)。反过来,如果某个新发布移除了某 feature,要求该 feature 的包会被"钉"在包含该 feature 的旧版本上。因此在 SemVer 兼容的发布中移除 feature 是不被鼓励的。还要注意:可选依赖会隐式定义一个同名 feature,因此移除可选依赖或把它改为非可选都可能引发问题,详见 semver.md 中关于移除可选依赖的说明。

Feature resolver version 2

当在 Cargo.toml 中指定 resolver = "2"(见下文 Resolver 版本)时,会启用一个算法不同的 feature 解析器。版本 "1" 的解析器无论依赖在何处声明,都会对包统一启用其 features;版本 "2" 的解析器在以下情况避免统一:

① 目标平台相关的 feature 不越界启用。若目标平台当前不在构建之列,其 [target] 段声明的 feature 不会被启用。例如:

[dependencies.common]
version = "1.0"
features = ["f1"]

[target.'cfg(windows)'.dependencies.common]
version = "1.0"
features = ["f2"]

在非 Windows 平台构建时,f2 feature 将不会被启用。

② build-dependencies 与 proc-macro 的 feature 不与普通依赖统一。例如:

[dependencies]
log = "0.4"

[build-dependencies]
log = {version = "0.4", features=['std']}

构建脚本使用 log 时带 std feature;而构建你的库本身时不会启用该 feature。

③ dev-dependencies 的 feature 不与普通依赖统一(除非这些 dev-dependencies 正在被构建)。例如:

[dependencies]
serde = {version = "1.0", default-features = false}

[dev-dependencies]
serde = {version = "1.0", features = ["std"]}

正常情况下库链接的 serde 不带 std feature;但作为测试或示例构建时(如 cargo test 或 cargo build --all-targets)会包含 std feature。注意:依赖包中的 dev-dependencies 始终被忽略,此规则只对顶层包或工作区成员生效。

关于 build-dependencies 与 dev-dependencies 的声明方式参见 specifying-dependencies.md。源码侧,feature resolver v2 由 src/resolver/features.rs 的 FeatureResolver 实现,其 track_for_host 字段(对应 decouple_host_deps 与 ignore_inactive_targets 选项)驱动了上述"按宿主/目标分离 feature"的行为。

links 字段约束

清单中的 links 字段用于保证某个原生库在最终二进制中只被链接一份。解析器会尝试找到满足"每个 links 名全局只出现一次"的图;若找不到满足该约束的图,则返回错误。

例如,一个包依赖 libgit2-sys 的 0.11,另一个包依赖 0.12,两者都会链接到 git2 这个原生库,而 Cargo 无法统一这两个版本,因此报错。正因为如此,如果你的库带有 links 字段且被广泛使用,发布 SemVer 不兼容版本时需要非常谨慎。

源码侧,RemainingCandidates::next 中的 links 检查(src/resolver/mod.rs 第 779-788 行)正是这条约束的实现:候选的 links 名若已被解析图中另一个不同包占用,则该候选被过滤,并记录 ConflictReason::Links。

Yanked 版本

被 yank(撤回)的版本会被标记为"不应使用"。解析器构建依赖图时会忽略所有 yanked 版本,除非它们已存在于 Cargo.lock 中,或被 cargo update --precise 标志显式请求(详见 cargo-update 命令文档)。

依赖更新(Dependency updates)

所有需要依赖图的 Cargo 命令都会自动执行依赖解析。例如 cargo build 会运行解析器找出需要构建的全部依赖;首次运行后结果存入 Cargo.lock,后续命令继续运行解析器,但只要可能就保持依赖锁定在 Cargo.lock 记录的版本上。

如果 Cargo.toml 的依赖列表发生修改(例如把某依赖的版本从 1.0 改为 2.0),解析器会为该依赖选择满足新要求的新版本;若新依赖带来新的要求,这些新要求也可能触发更多更新,Cargo.lock 会被更新为新的结果。--locked 或 --frozen 标志可以改变这一行为:要求变化时不再自动更新,而是直接返回错误。

cargo update 用于在新版本发布后更新 Cargo.lock 中的条目:

  • 不带任何选项时,尝试更新锁文件中的所有包;
  • -p 标志指定要更新的具体包;
  • --recursive、--precise 等标志控制版本选择方式(例如 --precise 可以精确指定版本,这在需要避开 yanked 版本或太新版本时很有用)。

Overrides(依赖覆盖)

Cargo 提供了若干覆盖依赖图中条目的机制,详见 Overriding Dependencies 一章。覆盖(如 [patch])表现为注册表之上的一个覆盖层(overlay),用新条目替换被 patch 的版本;除此之外,解析过程与常规无异。

源码中,patch 依赖会被记录进 VersionPreferences::prefer_patch_deps(src/resolver/version_prefs.rs 第 56-61 行),并在排序时被置为 preferred,从而优先被解析器选中。

依赖类型(Dependency kinds)与 dev-dependency 环

包中有三种依赖:普通(normal)、build 和 dev。从解析器的角度看,它们大部分被同等对待;一个差异是:非工作区成员的 dev-dependencies 总是被忽略,不参与解析。

带 <a href="https://link.gitcode.com/i/1f35cf9855eb64250d87b2140fcb656e" target="_blank">target] 表的[平台相关依赖会被视为所有平台全部启用来解析——也就是说,解析器忽略平台或 cfg 表达式本身(这与 feature resolver v2 按目标平台区分 feature 的行为形成对比:版本解析不分平台,feature 解析分平台)。

dev-dependency 环

通常解析器不允许图中出现环,但对 dev-dependencies 例外。例如项目 "foo" 有一个 dev-dependency 指向 "bar",而 "bar" 有一个指向 "foo" 的普通依赖(通常是 path 依赖)。这是允许的,因为从构建产物的角度看并不存在真正的环:先构建 "foo" 库(此时不需要 "bar",因为 "bar" 只用于测试),再构建依赖 "foo" 的 "bar",最后构建链接 "bar" 的 "foo" 测试。

但要小心由此产生的困惑性错误:构建库单元测试时,最终测试二进制里实际链接了两份库副本——一份与 "bar" 链接,一份包含单元测试本身。与版本不兼容的危害类似,这两份副本之间的类型互不兼容。如果 "bar" 在这种情况下暴露了 "foo" 的类型,foo 的单元测试不会把它们当成自己的本地类型。如果可能,尽量把包拆分成多个包并重构为严格无环的结构。

Resolver 版本

不同解析器行为可通过 Cargo.toml 中的 resolver 字段指定:

[package]
name = "my-package"
version = "1.0.0"
resolver = "2"

各版本含义:

MSRV: resolver 字段要求 Rust 1.51+。

解析器是一个影响整个工作区的全局选项:依赖中的 resolver 版本会被忽略,只有顶层包的值生效。如果使用虚拟工作区(virtual workspace),版本应写在 [workspace] 表中:

[workspace]
members = ["member1", "member2"]
resolver = "2"

源码侧,解析器版本的解析位于 src/resolver/types.rs 的 ResolveBehavior 枚举与 from_manifest 方法:"1" 对应 V1(原始行为)、"2" 对应 V2(新 feature 解析器)、"3" 对应 V3(改变版本偏好,即 MSRV fallback 默认值);非法值会得到错误提示 valid options are "1", "2" or "3"。

推荐实践(Recommendations)

以下是针对版本号设定与依赖要求声明方式的一般性建议,适用于常见场景(特殊情况当然可以声明非常规要求):

  • 决定如何更新版本号、是否需要做 SemVer 不兼容的版本变更时,遵循 SemVer 指南。
  • 大多数情况下对依赖使用 caret 要求(如 "1.2.3")。这能让解析器在维持构建兼容性的前提下拥有最大的选版灵活性。
    • 把当前所用版本的三个分量都写全。这有助于确定将使用的最低版本,避免其他用户拿到缺少你所需功能的旧版本。
    • 避免 * 要求:它不被 crates.io 允许,且普通 cargo update 可能因此拉入 SemVer 破坏性变更。
    • 避免过于宽泛的要求,如 >=2.0.0 可能拉入任何 SemVer 不兼容版本(比如 5.0.0),导致未来构建损坏。
    • 尽可能避免过于狭窄的要求。例如你写 bar = "~1.3",而另一个包写 bar = "1.4",即使 minor 版本本该兼容,也会解析失败。
  • 尽量让依赖要求与实际所需的最低版本保持同步。例如要求 bar = "1.0.12",而你在后续版本开始使用 1.1.0 新增的特性,就应把要求更新为 bar = "1.1.0"。
    • 若不做这件事,问题可能不会立刻显现:执行整仓 cargo update 时 Cargo 会机会主义地选择最新版本;但当其他用户依赖你的库并执行 cargo update your-library 时,若 "bar" 已锁在他们的 Cargo.lock 中,就不会自动更新——只有依赖声明也更新了才会更新。这种不一致会给他们带来令人困惑的构建错误。
  • 如果两个包紧密耦合,= 依赖要求有助于保持同步。例如一个库与其配套 proc-macro 库之间常有跨库假设,两者失同步时会出问题(且两者本不该被独立使用)。父库可以对 proc-macro 使用 = 要求,并 re-export 宏以方便使用。
  • 0.0.x 版本可用于永久不稳定的包。

总体而言:依赖要求写得越严格,解析越容易失败;反之写得太宽松,未来可能发布导致构建损坏的新版本。

故障排查(Troubleshooting)

这个依赖为什么被拉进来了?

假设你在 cargo check 输出里看到了依赖 rand,但觉得它不该出现,想弄明白它为何被引入。可以运行(--invert 反向展示依赖它的包):

$ cargo tree --workspace --target all --all-features --invert rand
rand v0.8.5
└── ...

rand v0.8.5
└── ...

这个依赖上的 feature 是被哪个包启用的?

你怀疑是某个被激活的 feature 导致 rand 出现。用 --edges features 找出是哪个包激活了该 feature:

$ cargo tree --workspace --target all --all-features --edges features --invert rand
rand v0.8.5
└── ...

rand v0.8.5
└── ...

意外的依赖重复

当你运行下面命令时看到了多个 rand 实例:

$ cargo tree --workspace --target all --all-features --duplicates
rand v0.7.3
└── ...

rand v0.8.5
└── ...

这是解析算法收敛到了包含两份依赖的解,而实际上单份即可满足。例如:

# Package A
[dependencies]
rand = "0.7"

# Package B
[dependencies]
rand = ">=0.6"  # 注意:这种开放要求是不被鼓励的

此例中 Cargo 可能构建两份 rand,尽管单份 0.7.3 就能满足所有要求。原因是解析算法为 Package B 倾向于构建最新可用版本(写此文时是 0.8.5),而它与 Package A 的要求不兼容。解析算法目前不会在这种情况下尝试"去重"。

Cargo 不鼓励 >=0.6 这类开放式版本要求。若遇到此情况,可用带 --precise 标志的 cargo update 手动消除重复。

为什么没有选到更新的版本?

你发现 cargo update 没有选中最新的依赖版本,可以开启额外的日志查看原因:

$ env CARGO_LOG=cargo::resolver=trace cargo update

[!NOTE] Cargo 的日志目标(log targets)与级别可能会随时间变化。

SemVer 破坏性 patch 版本破坏了构建

有时项目会无意中发布包含 SemVer 破坏性变更的 point release。用户执行 cargo update 后会拿到这个新版本,构建随之损坏。此时建议项目方 yank 该版本,并要么移除破坏性变更,要么以新的 SemVer 大版本发布。

如果变更来自第三方项目,尽量(礼貌地!)与项目方协作解决。

在等待撤回期间,可按情况采取以下变通措施:

  • 如果你的项目是最终产物(如二进制可执行文件),只需避免更新 Cargo.lock 中该包——用 cargo update 的 --precise 标志固定到已知良好的版本。
  • 如果你在 crates.io 上发布二进制,可临时加 = 要求把依赖钉在某个具体的好版本上。
    • 二进制项目也可以建议用户使用 cargo install 的 --locked 标志,以使用包含已知良好版本的原始 Cargo.lock。
  • 库项目可以考虑发布一个带更严格要求(避开问题依赖)的临时新版本。建议用范围要求(而非 =)避免与其他使用同一依赖的包冲突;问题解决后,再发布一个把依赖放宽回 caret 要求的 point release。
  • 如果第三方项目无法或不愿撤回,一个选项是更新你的代码以兼容这些变更,并把依赖要求的最低版本设为新版本。同时要考虑这会不会构成你自己库的 SemVer 破坏性变更(例如你暴露了该依赖中的类型)。

总结

依赖解析是 Cargo 中"约束求解"与"工程权衡"的交汇点:它在 NP-hard 的约束图上以"最高版本优先 + 回溯"的启发式算法工作,在 SemVer 兼容性、Cargo.lock 锁定、MSRV 兼容、发布年龄、links 唯一性、yanked 状态与 feature 统一之间寻找可行解。理解 src/resolver 中的实现脉络(resolve 入口、activate_deps_loop 主循环、VersionPreferences::sort_summaries 排序、RemainingCandidates 的过滤规则、FeatureResolver 的按目标区分 feature 逻辑),能帮助你更精准地预测解析结果;而 cargo tree、cargo update --precise、--locked 与解析器日志则是在实际项目中排查依赖问题的得力工具。选择合适的 resolver 版本(1/2/3)并遵循版本要求的推荐实践,可以让你的依赖图既稳定又可维护。

登录后查看全文
cargo