• 文档

导读

当你在~/.cargo/config.toml中通过[source.crates-io] replace-with把 crates.io 替换成镜像或本地 vendor 目录后，再执行cargo publish、cargo yank等 API 操作时，Cargo 的行为是混乱甚至危险的：crates.io 的凭据可能被误发给替换源，而报错信息也令人困惑。本篇文章基于 Rust RFC 流程仓库中的 RFC 3289 源文档，系统讲解该 RFC 提出的四项核心变更——强制--registry <NAME>消除歧义、对替换后的 crates-io 明确报错、凭据只发给同源 registry、以及让[source]表可引用[registries]表——并结合 RFC 3139 备选注册表认证 与 RFC 2141 备选注册表 的上下文，帮助你理解并安全配置 Cargo 的源码替换与多注册表凭据体系。

一、问题背景：源码替换在 API 操作上的行为不一致

Cargo 的源码替换（source replacement）是让crates-io这一内置源指向其他位置（本地目录、镜像、vendor 目录）的机制。它在拉取依赖时被 Cargo 尊重，但在执行 API 操作时却只对crates-io生效，对备选注册表完全不生效，行为并不一致。RFC 3289 在 Motivation 一节 中列出了它要解决的四个问题：

1. 不一致性：Cargo 执行 API 操作时，源码替换只对crates-io被尊重，对备选注册表不生效。同为 registry，行为却分叉。
2. 报错令人困惑：尝试向被替换的 crates-io 发布 crate 时，报错信息难以理解，而且除了临时删除源码替换配置外没有别的办法（对应 rust-lang/cargo#6722 描述的场景）。
3. 凭据泄露风险：执行publish之外的 API 操作时，如果crates-io源被替换，crates-io的凭据会被发送给替换 registry 的 API。这是明确的安全风险。
4. 凭据归属不清：当使用被替换的、需要认证的备选注册表（对应 RFC 3139 的场景）拉取依赖时，应该用哪一份凭据并不明确。

这四项问题都指向同一个根因：当crates-io被替换后，用户意图（发给原始 crates.io 还是发给替换源）无法被 Cargo 可靠推断，而 Cargo 默认行为又过于隐式。

二、Guide-level 设计：显式指定，杜绝隐式推断

RFC 3289 的 Guide-level explanation 给出了三条对用户友好的核心规则：

• 当crates-io源被替换后，执行 API 操作必须携带--registry <NAME>来明确指明使用哪个 registry，否则cargo直接报错。
• cargo只会把某个 registry 对应的 token 发送给该 registry 本身，即使配置了源码替换，也绝不会把 token 发给其他 registry。
• replace-with键可以引用[registries]表中注册的 registry 名称，打通源码替换与注册表配置两套体系。

场景一：本地 vendor（源码替换用于离线构建）

一个仓库在.cargo/config.toml中把 crates.io 的依赖全部 vendor 到本地目录。在此仓库内拉取依赖、构建，都使用 vendor 源，一切如常：

# .cargo/config.toml [source.crates-io] replace-with = "vendored-sources" [source.vendored-sources] directory = "vendor"

当开发者决定发布这个 crate 时，执行：

cargo publish --registry crates-io

--registry crates-io会忽略源码替换，直接发布到真正的 crates.io。发布动作与 vendor 配置互不干扰。

场景二：需要认证的 crates.io 镜像 registry

假设部署了一台提供 crates.io 完整镜像的服务器，并在~/.cargo/config.toml的[registries]表中配置了该镜像。镜像基于 RFC 3139 要求认证（config.json中设置auth-required = true）。

开发者先登录镜像：

cargo login --registry mirror

之后拉取与构建都走镜像源。当需要向 crates.io 发布时：

cargo login --registry crates-io cargo publish --registry crates-io

cargo login --registry crates-io登录到真正的 crates.io，token 被保存；cargo publish --registry crates-io在构建与发布时同样忽略源码替换，直达 crates.io。整个过程中，镜像的 token 只发给镜像，crates.io 的 token 只发给 crates.io。

三、Reference-level 设计：四项变更详解

变更 1：--registry优先于源码替换

执行 API 操作（login、logout、owner、publish、search、yank）时，Cargo 一律使用--registry <NAME>指定的 registry，绝不使用源码替换。这让显式参数成为唯一的权威来源，从机制上消除了"该用哪个源"的歧义。

变更 2：替换后的 crates-io 在 API 操作下明确报错

当执行上述 API 操作且同时满足以下全部条件时，cargo会报错：

• crates-io已被一个远程 registry 源替换（replace-with指向 registry 类型源）；
• 命令行未携带--registry <NAME>；
• 命令行未携带--index <URL>；
• Cargo.toml中的publish = <NAME>清单键未设置（该条件只对发布操作生效）。

报错信息如下：

error: crates-io is replaced: use `--registry replacement` or `--registry crates-io`

这条错误直接把解法写出来：要么用--registry replacement明确使用替换源，要么用--registry crates-io明确绕过替换。它替代了原先令人困惑的发布报错（rust-lang/cargo#6722），也消除了"临时删除配置才能发布"的痛苦。

变更 3：凭据只发给与其关联的同一个 registry

若crates-io被替换为另一个远程 registry，crates-io的凭据永远不会被发送给替换 registry。这一规则让crates-io与备选注册表的行为保持一致（备选注册表本来就各自持有各自 token），确保凭据只发给与其关联的 registry。这也是本 RFC 在安全层面的核心收益：即使镜像配置里config.json写明了 API 地址，token 也不会跨源流动。

结合 RFC 3139 备选注册表认证 可知，备选注册表通过 index 中config.json的auth-required: true要求认证，token 以Authorization: <token>HTTP 头携带，并且跟随重定向时不发送 Authorization 头（见该 RFC 的 Security 一节）。RFC 3289 的变更 3 正是把这一"凭据与源强绑定"的安全纪律推广到被替换的 crates-io 上。

变更 4：[source]表的replace-with可引用[registries]表

[source]表中的replace-with键现在可以引用[registries]表中定义的 registry。例如以下配置变得合法：

[source.crates-io] replace-with = "my-registry" [registries.my-registry] index = "https://my-registry-index/"

这是让--registry <NAME>命令行参数能够与源码替换后的 registry 配合工作的必要前提。同时它还带来一个实用收益：可以为替换源指定额外配置（例如 token），而不必在[registries]与[source]两处重复配置同一份信息。也就是说，被替换的 registry 可以复用备选注册表已有的认证与凭据体系（对应 RFC 2141 备选注册表 引入的[registries]表及其后续演进），让源码替换与多注册表模型在同一套配置框架下自洽。

四、缺陷与取舍：破坏性在哪里

RFC 在 Drawbacks 中坦承了两点：

• 行为变更：凭据发送位置发生变化，可能破坏某些既有工作流。
• 镜像场景受影响：如果 crates.io 镜像的config.json中配置了"api": "https://crates.io"，那么旧行为（把 crates.io token 发给替换源）恰好能正常工作，而本 RFC 会打破这种配置下的可用性——因为 token 不再发给替换源了。

这正是该 RFC 在设计上刻意选择"显式优于隐式"的代价：旧行为在特定镜像配置下"碰巧能用"，但本质上是凭据跨源发送的安全隐患，RFC 选择用显式参数换取安全与一致。

五、备选方案回顾：为什么不用别的解法

RFC 在 Rationale and alternatives 中评估了两个主要备选方案：

方案 A：API 操作默认忽略源码替换（可选的--respect-source-config）

备选注册表目前就是这么做的：API 操作默认忽略替换。可以再加一个--respect-source-config选项让 cargo 在 API 操作时遵循源码替换（类似cargo vendor的已有行为）。但这样会静默改变行为，对用户来说过于隐晦——你可能根本没意识到发布到的是替换源。RFC 认为歧义场景下必须强制用户显式指定。

方案 B：禁止对替换源执行 API 操作

对替换源执行 API 操作一律报错，用户必须用--registry crates-io显式绕过替换：

Error: <operation> is not supported on replaced source `crates-io-mirror`; use `--registry crates-io` for the original source

这个方案更严格，但把"用替换源做 API 操作"这条路完全堵死，灵活度不如最终方案。

最终方案取两者之长：既保留显式绕过（--registry crates-io），又保留使用替换源的可能（--registry replacement），并把选择权完全交给用户。

六、未决问题与后续

RFC 在 Unresolved questions 中留下两个开放问题：

1. --registry <NAME>是否也应允许引用[source]表中的 source 名称？这样更灵活，但会带来不必要的复杂度。
2. Cargo 自身测试依赖"替换 crates-io 源并把 crates-io 凭据发给替换源"的能力，需要为这些测试找到继续工作的方式。

此外，RFC 在 Prior art 中指出：其他包管理器似乎并没有源码替换功能，因此缺乏现成的同类设计可参照；Future possibilities 则未提出后续扩展。

七、实操要点总结

需要说明的是：本 RFC 属于 Cargo 的规范设计文档（位于本仓库 text/3289-source_replacement_ambiguity.md，配套实现追踪于 rust-lang/cargo 的 #10894），文章中的命令行为与报错文案以其设计为准；实际使用前建议对照当前 Cargo 版本的行为验证。对于更完整的备选注册表索引格式与认证细节，可继续阅读 RFC 2141 与 RFC 3139。

• 文档