Cargo 依赖覆盖（Overriding Dependencies）完全指南：[patch]、[replace] 与 paths 的实战与源码解析

导读：当你在修改一个尚未发布到 crates.io 的库、希望提前试用上游 git 分支的新特性、或为一次破坏性的大版本升级做集成测试时，Cargo 提供的依赖覆盖机制是唯一正规的出路。本文以 Cargo Book 官方文档 overriding-dependencies.md 为主线，完整讲解 <a href="https://link.gitcode.com/i/1362c03a114f7cd630edfc9288556967" target="_blank">patch]、已废弃的 [replace] 以及 paths 路径覆盖三种方式的使用场景、配置语法与限制，并结合当前 Cargo 仓库源码（[resolve.rs、parser/mod.rs、registry.rs）与测试用例（patch.rs、replace.rs）剖析其底层工作方式。读完本文，你将能够在自己的项目中安全、精准地临时或长期替换任意依赖的来源。

为什么需要覆盖依赖

覆盖依赖的需求通常源于「在 crate 发布到 crates.io 之前就要用上它」这一核心诉求，典型场景包括：

• 你正在开发的 crate 同时被一个更大的应用使用，你想在大型应用中测试对该库的 bug 修复；
• 某个上游 crate 的 git 仓库 master 分支上有了新特性或修复，你想提前试用；
• 你即将发布 crate 的新大版本，希望在完整依赖图上做集成测试，确保新主版本可用；
• 你已向上游提交了 bug 修复，但希望应用立刻依赖修复后的版本，而不是干等合并发布。

这些场景都可以通过清单文件中的 [patch] 段 来解决。此外还有两种辅助/历史机制：[replace] 段（已废弃）与 paths 覆盖。它们都遵循一个共同原则：让本地包在解析依赖时，把某个来源（source）中的指定 crate 换成另一个副本。

[!NOTE] 除了本文的三种全局覆盖方式外，还可以在 specifying-dependencies.md 中了解「多重位置」声明依赖的方式——它只作用于本地包中单条依赖声明的来源覆盖，与本文的全局覆盖相互补充。

实战一：测试一个 bug 修复（path 覆盖）

假设你正在使用 uuid crate 并发现了 bug，决定自己动手修复。最初的清单如下：

[package]
name = "my-library"
version = "0.1.0"

[dependencies]
uuid = "1.0"

第一步，把 uuid 的仓库克隆到本地：

$ git clone https://github.com/uuid-rs/uuid.git

第二步，编辑 my-library 的清单，加入 [patch] 段：

[patch.crates-io]
uuid = { path = "../path/to/uuid" }

这里声明的是：用本地新副本 修补（patch） crates-io 这个来源。效果等同于把本地签出的 uuid 版本"注入"到 crates.io 注册表中，供当前包使用。注意 <a href="https://link.gitcode.com/i/f05ba3ba2c93cbe79feff715d2ac8545" target="_blank">patch] 的键名必须用 crates-io（带连字符）——若写成 crates，Cargo 会报错并提示 "For crates.io, use [patch.crates-io] (with a dash)"，这一点在 [parser/mod.rs 的解析逻辑中有专门处理。

第三步，构建即可让锁文件（lock file）更新为使用本地版本：

$ cargo build
   Compiling uuid v1.0.0 (.../uuid)
   Compiling my-library v0.1.0 (.../my-library)
    Finished dev [unoptimized + debuginfo] target(s) in 0.32 secs

[patch] 的工作方式是：加载 ../path/to/uuid 的依赖后，每当查询 crates.io 上 uuid 的版本时，会同时返回本地版本。因此有一个关键点需要注意：

本地签出版本的版本号具有决定性。若清单声明 uuid = "1.0"，解析范围是 >= 1.0.0, < 2.0.0，而 Cargo 的贪心解析算法会选择范围内的最大版本。通常 git 仓库中的版本已等于或大于 crates.io 上发布的最大版本，所以影响不大，但务必牢记这一点。

如果构建输出中（如上）看不到本地路径版本被编译，可能需要手动指定精确版本：

$ cargo update uuid --precise $version

其中 $version 是本地 uuid 签出副本的版本号。

修复完成后向上游提交 PR，等 PR 合并后，可以把 [patch] 中的 path 依赖换成 git 依赖，让后续构建始终跟踪上游仓库（列表语法与 [dependencies] 完全一致）：

[patch.crates-io]
uuid = { git = 'https://github.com/uuid-rs/uuid.git' }

这一场景在测试套件中有完整对应：tests/testsuite/patch.rs 中的 replace 测试（patch.rs）构建了一个发布到 dummy-registry 的 bar 与依赖 bar 的 baz，再用 [patch.crates-io] bar = { path = "bar" } 覆盖，最终构建输出 [CHECKING] bar v0.1.0 ([ROOT]/foo/bar)，路径来自本地——与文档中的构建输出完全一致。

实战二：使用未发布的小版本（git 覆盖与传递性）

从修 bug 转向加特性：你在 uuid 中实现了一个新特性，本地测试通过并已提交 PR，但该版本尚未发布。假设 crates.io 上的当前版本是 1.0.0，而 git 仓库 master 分支已更新到 1.0.1（包含你的特性）。编辑 Cargo.toml：

[package]
name = "my-library"
version = "0.1.0"

[dependencies]
uuid = "1.0.1"

[patch.crates-io]
uuid = { git = 'https://github.com/uuid-rs/uuid.git' }

注意依赖声明已升级到 1.0.1——这是发布后实际会要求的版本。这个版本目前在 crates.io 上不存在，因此由 [patch] 提供。构建时 Cargo 会从 git 仓库获取 uuid 并解析到其中的 1.0.1，而不是尝试从 crates.io 下载。一旦 1.0.1 正式发布到 crates.io，就可以删除整个 [patch] 段。

[patch] 具有传递性

[patch] 传递生效：假设 my-library 被一个更大的包 my-binary 使用：

[package]
name = "my-binary"
version = "0.1.0"

[dependencies]
my-library = { git = 'https://example.com/git/my-library' }
uuid = "1.0"

[patch.crates-io]
uuid = { git = 'https://github.com/uuid-rs/uuid.git' }

关键规则有两条：

1. [patch] 传递生效，但只能在顶层定义——my-library 清单里的 [patch] 不会被 my-binary 继承，消费方如需补丁必须自行重复声明；
2. 顶层 [patch] 会同时作用于本包的直接依赖与传递依赖：这里新的 uuid 同时覆盖 my-binary → uuid 与 my-library → uuid 两条边，整个依赖图中 uuid 统一解析为一个版本（1.0.1），且取自 git 仓库。

transitive_new_minor（patch.rs）与 transitive_new_major（patch.rs）两个测试分别验证了小版本与大版本在传递依赖场景下的解析行为。

覆盖 git 来源：覆盖仓库 URL

如果被覆盖的依赖不是来自 crates.io，而是 git 依赖，[patch] 的键就不能用 crates-io，而要换成被覆盖来源的 URL：

[patch."https://github.com/your/repository"]
my-library = { path = "../my-library/path" }

即 <a href="https://link.gitcode.com/i/30eeb5edbd4f3a5a35079c4b757894a8" target="_blank">patch] 段的每个子键可以是注册表名，也可以是来源 URL；[patch.crates-io] 只是覆盖默认注册表 crates.io 的特例。在 [parser/mod.rs 的 patch() 解析函数中可以看到：crates-io 被映射到 crates.io 索引 URL，其他键则先尝试当作注册表名解析（get_registry_index），失败后按 URL 解析（into_url）。

实战三：发布前的破坏性变更（多版本共存）

现在处理新大版本（伴随破坏性变更）。为 uuid 创建 2.0.0 后，更新 my-library 清单：

[dependencies]
uuid = "2.0"

[patch.crates-io]
uuid = { git = "https://github.com/uuid-rs/uuid.git", branch = "2.0.0" }

与上一例同理：2.0.0 尚未发布到 crates.io，但可以通过 git 依赖配合 [patch] 提前引入。此时再看 my-binary 的清单：

[package]
name = "my-binary"
version = "0.1.0"

[dependencies]
my-library = { git = 'https://example.com/git/my-library' }
uuid = "1.0"

[patch.crates-io]
uuid = { git = 'https://github.com/uuid-rs/uuid.git', branch = '2.0.0' }

注意：这次会解析出两个版本的 uuid。my-binary 本身继续使用 1.x.y 系列，而 my-library 使用 2.0.0。这就允许你在依赖图上渐进式铺开破坏性变更，不必一次性升级所有依赖。其底层机制在 registry.rs 的 PackageRegistry::patch 中实现——补丁按被修补的来源 URL 分组挂载，解析时各依赖按其版本约束从对应来源取用，因此不同约束可以命中不同的补丁/原版组合。

实战四：[patch] 同一 crate 的多个版本（package 键重命名）

假设 serde 的 1.* 系列有个 bug 修复想引入，同时还想在 git 仓库中试用 2.0.0 原型：

[patch.crates-io]
serde = { git = 'https://github.com/serde-rs/serde.git' }
serde2 = { git = 'https://github.com/example/serde.git', package = 'serde', branch = 'v2' }

• 第一条 serde = ...：serde 1.* 从 git 仓库取用（包含所需 bug 修复）；
• 第二条 serde2 = ...：用 package = 'serde' 键指示该条目仍修补 serde 包，但取自 https://github.com/example/serde 的 v2 分支（假设该分支的 Cargo.toml 中版本为 2.0.0）。

使用 package 键时，serde2 这个标识符本身被忽略——它只是需要一个与其他被修补 crate 不冲突的唯一名称，用于在同一来源下挂多个补丁条目。这与 <a href="https://link.gitcode.com/i/33178ca32ee2d05ff0e11dfab806ff48" target="_blank">dependencies] 中利用 package 重命名依赖的语法同源，可参考 [specifying-dependencies.md 中关于重命名的说明。

The [patch] section 参考

[patch] 段是 Cargo.toml 中用来「用其他副本覆盖依赖」的标准机制，语法与 [dependencies] 段相似：

[patch.crates-io]
foo = { git = 'https://github.com/example/foo.git' }
bar = { path = 'my/local/bar' }

[dependencies.baz]
git = 'https://github.com/example/baz.git'

[patch.'https://github.com/example/baz']
baz = { git = 'https://github.com/example/patched-baz.git', branch = 'my-branch' }

语法要点：

• [patch] 表由「类似依赖的子表」构成，每个子键是被修补来源的 URL 或 注册表名；crates-io 特指默认注册表 crates.io；
• 上例第一个 [patch] 覆盖 crates.io，第二个覆盖 git 来源 https://github.com/example/baz；
• 每个条目都是与 [dependencies] 完全一致的普通依赖声明（支持 git、path、branch、package 等键），这些依赖会被解析并用于修补指定 URL 的来源；
• 被修补来源可以挂上「来源中不存在的版本」，也可以挂「已存在的版本」——若修补的版本在来源中已存在，则来源中的原版 crate 会被替换。

[!NOTE] <a href="https://link.gitcode.com/i/f66de70058a15539c8a18d2875bbbde1" target="_blank">patch] 表也可以写成[配置选项的形式：放在 .cargo/config.toml 文件中，或用 CLI 参数如 --config 'patch.crates-io.rand.path="rand"'。这非常适合不想提交到仓库的本地改动，或临时测试某个补丁。

配置与清单中 [patch] 的合并规则（源码视角）

从源码看，Cargo 对配置文件的 <a href="https://link.gitcode.com/i/3c9f2f30b12f762b730ddfeed78ff0f8" target="_blank">patch] 支持是完整的：Workspace::config_patch（[workspace.rs）会从全局配置读取 patch 键并同样转换为补丁依赖；而 root_patch（workspace.rs）负责合并「清单中的补丁」与「配置中的补丁」——两者都存在时，配置优先于清单，逐条覆盖同名补丁。测试 from_config（patch.rs）正是验证了把 [patch.crates-io] bar = { path = 'bar' } 写进 .cargo/config.toml 后，bar 被替换为本地 1.0.1 的完整流程。

只认工作区根清单

Cargo 只会读取工作区根 Cargo.toml 中的补丁设置，依赖（子 crate）中定义的补丁设置会被忽略。解析入口 resolve.rs 的 register_patch_entries 遍历的正是 ws.root_patch()?——只取根清单/根虚拟清单的补丁。

未被使用的补丁会怎样

解析完成后，resolve.rs 中的 emit_warnings_of_unused_patches 会逐个检查：如果某个 <a href="https://link.gitcode.com/i/523a9d91f4e7b7df501cda3477e4137a" target="_blank">patch] 条目没有在最终解析结果中被使用（例如其版本与依赖约束不匹配、或对应来源根本没有被依赖），Cargo 会发出 patch \` was not used in the crate graph之类的警告，并尽可能提示候选的替代来源 URL。对应测试包括unused、unused_git、unused_from_config、unused_with_mismatch_source_being_patched`（[patch.rs）。

The [replace] section（已废弃）

[!IMPORTANT] [replace] 已废弃，应改用 [patch] 段。

[replace] 段同样用于以其他副本覆盖依赖，语法与 [dependencies] 相似：

[replace]
"foo:0.1.0" = { git = 'https://github.com/example/foo.git' }
"bar:1.0.2" = { path = 'my/local/bar' }

语义要点：

• 每个键是一个 package ID 规范（pkgid-spec），可以任意指定依赖图中要覆盖的节点，必须包含三段式版本号（如 0.1.0）；
• 每个键的值与 [dependencies] 语法相同，但不能指定 features；
• 覆盖时，替代副本必须与原 crate 同名且同版本，但可以来自不同来源（git 或本地路径）；
• 与 [patch] 一样，[replace] 只在工作区根清单中生效，依赖中定义的替换设置会被忽略。

从源码可见废弃状态下的严格性：parser/mod.rs 的 replace() 解析函数会：

• 拒绝同时指定 [replace] 与 [patch]（cannot specify both [replace] and [patch]）；
• 要求 key 是合法的 semver 版本（否则报 replacements must specify a valid semver version to replace）；
• 拒绝在替换值里再写版本约束（replacements cannot specify a version requirement）；
• 内部会把被替换版本的依赖约束设为精确匹配（OptVersionReq::exact）。

测试套件 replace.rs 覆盖了 override_simple、override_with_features、missing_version、invalid_semver_version、different_version、transitive、replace_registry_with_path 等场景；解析阶段对锁文件历史替换的锁定由 resolve.rs 的 lock_replacements 完成。

paths 覆盖（path overrides）

当你只是临时改一个 crate、又不想像 [patch] 那样修改 Cargo.toml 时，Cargo 提供了功能受限得多的「路径覆盖」（path overrides）。

路径覆盖通过 .cargo/config.toml 指定，而不是 Cargo.toml。在 .cargo/config.toml 中写一个 paths 键：

paths = ["/path/to/uuid"]

要点：

• 数组元素是包含 Cargo.toml 的目录；上例中只有 uuid，因此只覆盖它；
• 路径可以是绝对路径，也可以是相对于包含 .cargo 文件夹的目录的相对路径；
• 路径覆盖比 [patch] 更受限：它不能改变依赖图的结构。使用路径替换后，新的 Cargo.toml 声明必须与原先的依赖集合完全一致——例如不能用路径覆盖来测试「给某个 crate 新增一个依赖」；这种改动必须用 [patch] 完成。因此路径覆盖通常只用于快速 bug 修复，而非较大改动。

[!NOTE] 用本地配置做路径覆盖只对已发布到 crates.io 的 crate 生效。你不能用它告诉 Cargo 去哪里找本地尚未发布的 crate。

路径覆盖与 <a href="https://link.gitcode.com/i/431fa87a39f0c5c8085ed5fd154869ea" target="_blank">patch] 的另一处差异在解析器中亦有体现：当某来源既存在补丁又存在路径覆盖时，[registry.rs 会直接报错 found patches and a path override，提示两种机制不可混用于同一来源。

三种机制的选型建议

机制	定义位置	能否改变依赖图结构	典型场景	状态
[patch]	工作区根 Cargo.toml 或 .cargo/config.toml / --config	可以	覆盖到 git 分支、本地路径、预发布新版本、多版本共存	推荐
[replace]	工作区根 Cargo.toml	可以（但须同名同版本）	按包 ID 精确替换图中某个节点	已废弃
paths	.cargo/config.toml	不可以	临时快速修 bug，不改清单	保留

选择建议：日常开发优先 [patch]；只想在本地临时试一下、不想污染 Cargo.toml 时，把 [patch] 写进 .cargo/config.toml 或用 --config 传参；paths 覆盖适合纯本地、零清单改动的快速验证；遗留项目中遇到 [replace] 应迁移到 [patch]。

深入阅读

• 官方章节原文：overriding-dependencies.md
• 依赖声明基础（多重位置、重命名）：specifying-dependencies.md
• 配置文件（.cargo/config.toml、--config）：config.md
• 包 ID 规范（<a href="https://link.gitcode.com/i/ad840d7f37e6949db4560857d26efac1" target="_blank">replace] 键的语法）：[pkgid-spec.md
• 解析入口与补丁注册/锁定：src/ops/resolve.rs
• 清单解析（<a href="https://link.gitcode.com/i/aaf0b56d872c4b8ca3461b3f6f9ef5da" target="_blank">patch]/[replace] 的语法校验与错误提示）：[src/workspace/parser/mod.rs
• 工作区层面的补丁合并（清单 + 配置）：src/workspace/workspace.rs
• 包注册表层的补丁挂载与锁定：PackageRegistry::patch / lock_patches（src/workspace/registry.rs）
• 测试用例：tests/testsuite/patch.rs、tests/testsuite/replace.rs